> For the complete documentation index, see [llms.txt](https://docs.insurehero.io/shield-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.insurehero.io/shield-api/policies/subscriptions.md).

# Subscriptions

## Endpoints

<table><thead><tr><th width="113">Method</th><th>Endpoint</th></tr></thead><tbody><tr><td><mark style="color:orange;">PATCH</mark></td><td><a href="#cancelations"><code>https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/cancel</code></a></td></tr><tr><td><mark style="color:red;">DELETE</mark></td><td><a href="#risk-item-rescission"><code>https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/rescission</code></a></td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><a href="#get-all-the-subscriptions"><code>https://app.insurehero.io/api/shield/v1/subscriptions</code></a></td></tr></tbody></table>

## Overview

Subscriptions are generated from the creation of a Risk Item, which includes a package containing pre-configured settings for recurring payments. These subscriptions can be daily, weekly, monthly, or annual, and may feature a trial period. Additionally, they can specify whether the payment is charged at the end of the month, at the beginning, or upon the expiration of the last payment.

The process begins with the creation of a Risk Item. A webhook then evaluates whether the Risk Item is a one-time payment or a subscription. For one-time payments, an order is created immediately, and the Risk Item is protected until the specified `end_date`. For subscriptions, protection is provided based on payment renewal, using the `end_date` as the final date of the subscription (with the option to set the `end_date` to `null` to indicate that the subscription does not expire).

Once the subscription and the first order are created, the next payment date is generated and stored in the database. A CRON job runs daily at night to generate new orders for subscriptions, continuing this process until the subscription ends.

Use cases include daily, weekly, monthly, and annual subscriptions, where Risk Items are protected and orders are generated according to the specified intervals. Subscriptions can also include a trial period, delaying the first payment for a defined duration. The payment schedule is flexible, allowing payments to be scheduled at the end of the month, the beginning of the month, or upon the expiration of the last payment, based on the package configuration.

## Cancelations

To cancel a subscription, you need the ID or UID of the Risk Item to be canceled. This allows you to terminate the subscription or modify its end date. It is important to note that if you cancel midway through a monthly subscription, you remain protected for the month you paid for, and protection ceases once the paid subscription period ends.

<mark style="color:orange;">`PATCH`</mark> `https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/cancel`

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

#### Path Parameters

| Name                                           | Type   | Description          |
| ---------------------------------------------- | ------ | -------------------- |
| `riskItemId`<mark style="color:red;">\*</mark> | string | Risk item identifier |

#### &#x20;Body

| Name                                        | Type | Description                                                               |
| ------------------------------------------- | ---- | ------------------------------------------------------------------------- |
| end\_date<mark style="color:red;">\*</mark> | date | End date of the Risk item. If you send "cancel" the current date is sent. |

#### Example response

{% tabs %}
{% tab title="200: OK Retrieved successfully" %}

```json
{
    "data": {
        "id": "943511e3-de9a-4afb-a126-b434ebd1f84e",
        "policy_id": "c42a9583-9a58-4b0c-b332-21499780a35b",
        "authorized_claimants": [
            {
                "email": "luciamartinez@example.com",
                "name": "Lucia Martinez",
                "phone": "593999002823"
            },
            {
                "email": "marcoreyes@example.com",
                "name": "Marco Reyes",
                "phone": "593999002824"
            }
        ],
        "package_id": "12e02904-0ab6-41e5-a66f-14fe5d981960",
        "start_date": "2024-03-15T00:00:00+00:00",
        "end_date": "2024-03-31T23:59:59.999+00:00",
        "beneficiaries": [
            {
                "email": "anatorres@example.com",
                "phone": "593999002825"
            }
        ],
        "insured_subject": {
            "identifier_value": "GN789",
            "identifier_type": "Guide Number",
            "ruc": "1711186642001",
            "driver_id": "1714486642",
            "group_uid": "yourUID01",
            "group_name": "Ecuador Transport",
            "policy_note": "Insured against theft and damage",
            "guide_number": "GN789",
            "plate_number": "PICH1234",
            "subject_type": "cargo",
            "invoice_count": 10,
            "departure_city": "Guayaquil",
            "departure_date": "2024-01-24T09:00:00Z",
            "content_category": "Clothing",
            "departure_coords": "-2.170998, -79.922359",
            "destination_city": "Quito",
            "driver_full_name": "Luis Andrade",
            "primary_category": "Men's Apparel",
            "business_industry": "Consumo Masivo",
            "policy_observations": "Fragile items inside",
            "total_insured_value": 75000
        },
        "status": "ACTIVE",
        "uid": null,
        "assets": [],
        "metadata": {
            "delivery_stops": {
                "Delivery 1": {
                    "items": [
                        {
                            "item_sku": "LAP1234A",
                            "item_cost": 1200,
                            "item_name": "Laptop",
                            "item_expiry": "2024-12-31",
                            "item_quantity": 10
                        }
                    ],
                    "final_coords": "-0.180653, -78.467838",
                    "destination_invoice_id": "INV1001"
                }
            }
        }
    }
}
```

{% endtab %}

{% tab title="400: Bad Request Request contains malformed data" %}

{% endtab %}

{% tab title="401: Unauthorized Invalid or expired access token" %}

{% endtab %}

{% tab title="402: Payment Required Pending payment" %}

{% endtab %}

{% tab title="422: Unprocessable Entity Internal validation failed" %}

{% endtab %}

{% tab title="429: Too Many Requests API rate limit" %}

{% endtab %}

{% tab title="404: Not Found User not found" %}

{% endtab %}
{% endtabs %}

#### Attributes

<table><thead><tr><th>Name</th><th width="113">Type</th><th>Description</th></tr></thead><tbody><tr><td>data</td><td>object</td><td>aObject containing information about a risk item</td></tr><tr><td>id</td><td>uuid</td><td>Unique identifier for the risk item</td></tr><tr><td>policy_id</td><td>uuid</td><td>Unique identifier for the associated policy</td></tr><tr><td>authorized_claimants</td><td>object []</td><td>List of authorized claimants</td></tr><tr><td>authorized_claimants.email</td><td>string</td><td>Email of the authorized claimant</td></tr><tr><td>authorized_claimants.name</td><td>string</td><td>Name of the authorized claimant</td></tr><tr><td>authorized_claimants.phone</td><td>string</td><td>Phone number of the authorized claimant</td></tr><tr><td>package_id</td><td>uuid</td><td>Unique identifier for the coverage package</td></tr><tr><td>start_date</td><td>string</td><td>Start date of the coverage period</td></tr><tr><td>end_date</td><td>string</td><td>End date of the coverage period</td></tr><tr><td>beneficiaries</td><td>object []</td><td>List of beneficiaries</td></tr><tr><td>beneficiaries.email</td><td>string</td><td>Email of the beneficiary</td></tr><tr><td>beneficiaries.name</td><td>string</td><td>Name of the beneficiary</td></tr><tr><td>beneficiaries.phone</td><td>string</td><td>Phone number of the beneficiary</td></tr><tr><td>beneficiaries.group_uid</td><td>string</td><td>Unique identifier for the beneficiary’s group</td></tr><tr><td>insured_subject</td><td>object</td><td>Details of the insured subject</td></tr><tr><td>insured_subject.identifier_value</td><td>string</td><td>Identifier of the insured subject</td></tr><tr><td>insured_subject.identifier_type</td><td>string</td><td>Type of identifier</td></tr><tr><td>insured_subject.ruc</td><td>string</td><td>Taxpayer identification number</td></tr><tr><td>insured_subject.driver_id</td><td>string</td><td>Driver's identification number</td></tr><tr><td>insured_subject.group_uid</td><td>string</td><td>Unique identifier of the insured group</td></tr><tr><td>insured_subject.group_name</td><td>string</td><td>Name of the insured group</td></tr><tr><td>insured_subject.policy_note</td><td>string</td><td>Policy coverage notes</td></tr><tr><td>insured_subject.guide_number</td><td>string</td><td>Tracking number for the shipment</td></tr><tr><td>insured_subject.plate_number</td><td>string</td><td>License plate of the transport vehicle</td></tr><tr><td>insured_subject.subject_type</td><td>string</td><td>Type of insured subject</td></tr><tr><td>insured_subject.invoice_count</td><td>number</td><td>Number of invoices related to the insured subject</td></tr><tr><td>insured_subject.departure_city</td><td>string</td><td>City of departure</td></tr><tr><td>insured_subject.departure_date</td><td>string</td><td>Departure date and time</td></tr><tr><td>insured_subject.content_category</td><td>string</td><td>Category of the transported content</td></tr><tr><td>insured_subject.departure_coords</td><td>string</td><td>GPS coordinates of departure location</td></tr><tr><td>insured_subject.destination_city</td><td>string</td><td>Destination city</td></tr><tr><td>insured_subject.driver_full_name</td><td>string</td><td>Full name of the driver</td></tr><tr><td>insured_subject.primary_category</td><td>string</td><td>Main category of insured items</td></tr><tr><td>insured_subject.business_industry</td><td>string</td><td>Industry related to the insured subject</td></tr><tr><td>insured_subject.policy_observations</td><td>string</td><td>Additional observations about the policy</td></tr><tr><td>insured_subject.total_insured_value</td><td>number</td><td>Total insured value in policy currency</td></tr><tr><td>status</td><td>string</td><td>Current status of the risk item</td></tr><tr><td>uid</td><td>string</td><td>Unique identifier</td></tr><tr><td>assets</td><td>object[]</td><td>List of associated assets</td></tr><tr><td>metadata</td><td>object</td><td>Additional structured data</td></tr><tr><td>metadata.delivery_stops</td><td>object</td><td>Details of delivery stops</td></tr><tr><td>metadata.delivery_stops.[key]</td><td>object</td><td>Delivery stop information</td></tr><tr><td>metadata.delivery_stops.[key].items</td><td>object[]</td><td>List of items delivered at this stop</td></tr><tr><td>metadata.delivery_stops.[key].items.item_sku</td><td>string</td><td>Stock-keeping unit (SKU) of the item</td></tr><tr><td>metadata.delivery_stops.[key].items.item_cost</td><td>number</td><td>Cost of the item</td></tr><tr><td>metadata.delivery_stops.[key].items.item_name</td><td>string</td><td>Name of the item</td></tr><tr><td>metadata.delivery_stops.[key].items.item_expiry</td><td>string</td><td>Expiry date of the item</td></tr><tr><td>metadata.delivery_stops.[key].items.item_quantity</td><td>number</td><td>Quantity of the item</td></tr><tr><td>metadata.delivery_stops.[key].final_coords</td><td>string</td><td>GPS coordinates of delivery stop</td></tr><tr><td>metadata.delivery_stops.[key].destination_invoice_id</td><td>string</td><td>Invoice ID for delivered items</td></tr></tbody></table>

### Risk Item Rescission&#x20;

This endpoint is useful for canceling a risk-item immediately

<mark style="color:red;">`DELETE`</mark> `https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/rescission`

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

#### Path Parameters

| Name                                           | Type   | Description          |
| ---------------------------------------------- | ------ | -------------------- |
| `riskItemId`<mark style="color:red;">\*</mark> | string | Risk item identifier |

#### Example response

{% tabs %}
{% tab title="200: OK Retrieved successfully" %}

```json
{
    "data": {
        "id": "943511e3-de9a-4afb-a126-b434ebd1f84e",
        "policy_id": "c42a9583-9a58-4b0c-b332-21499780a35b",
        "authorized_claimants": [
            {
                "email": "luciamartinez@example.com",
                "name": "Lucia Martinez",
                "phone": "593999002823"
            },
            {
                "email": "marcoreyes@example.com",
                "name": "Marco Reyes",
                "phone": "593999002824"
            }
        ],
        "package_id": "12e02904-0ab6-41e5-a66f-14fe5d981960",
        "start_date": "2024-03-15T00:00:00+00:00",
        "end_date": "2024-06-10T17:33:41.524+00:00",
        "beneficiaries": [
            {
                "email": "anatorres@example.com",
                "phone": "593999002825"
            }
        ],
        "insured_subject": {
            "identifier_value": "GN789",
            "identifier_type": "Guide Number",
            "ruc": "1711186642001",
            "driver_id": "1714486642",
            "group_uid": "yourUID01",
            "group_name": "Ecuador Transport",
            "policy_note": "Insured against theft and damage",
            "guide_number": "GN789",
            "plate_number": "PICH1234",
            "subject_type": "cargo",
            "invoice_count": 10,
            "departure_city": "Guayaquil",
            "departure_date": "2024-01-24T09:00:00Z",
            "content_category": "Clothing",
            "departure_coords": "-2.170998, -79.922359",
            "destination_city": "Quito",
            "driver_full_name": "Luis Andrade",
            "primary_category": "Men's Apparel",
            "business_industry": "Consumo Masivo",
            "policy_observations": "Fragile items inside",
            "total_insured_value": 75000
        },
        "status": "INACTIVE",
        "uid": null,
        "assets": [],
        "metadata": {
            "delivery_stops": {
                "Delivery 1": {
                    "items": [
                        {
                            "item_sku": "LAP1234A",
                            "item_cost": 1200,
                            "item_name": "Laptop",
                            "item_expiry": "2024-12-31",
                            "item_quantity": 10
                        }
                    ],
                    "final_coords": "-0.180653, -78.467838",
                    "destination_invoice_id": "INV1001"
                }
            }
        }
    }
}
```

{% endtab %}
{% endtabs %}

#### Attributes

<table><thead><tr><th width="214">Name</th><th width="113">Type</th><th>Description</th></tr></thead><tbody><tr><td>data</td><td>object</td><td>Object containing information about a risk item</td></tr><tr><td>id</td><td>uuid</td><td>Unique identifier for the risk item</td></tr><tr><td>policy_id</td><td>uuid</td><td>Unique identifier for the associated policy</td></tr><tr><td>authorized_claimants</td><td>object[]</td><td>List of authorized claimants</td></tr><tr><td>authorized_claimants.email</td><td>string</td><td>Email of the authorized claimant</td></tr><tr><td>authorized_claimants.name</td><td>string</td><td>Name of the authorized claimant</td></tr><tr><td>authorized_claimants.phone</td><td>string</td><td>Phone number of the authorized claimant</td></tr><tr><td>package_id</td><td>uuid</td><td>Unique identifier for the coverage package</td></tr><tr><td>start_date</td><td>string</td><td>Start date of the coverage period</td></tr><tr><td>end_date</td><td>string</td><td>End date of the coverage period</td></tr><tr><td>beneficiaries</td><td>object []</td><td>List of beneficiaries</td></tr><tr><td>beneficiaries.email</td><td>string</td><td>Email of the beneficiary</td></tr><tr><td>beneficiaries.name</td><td>string</td><td>Name of the beneficiary</td></tr><tr><td>beneficiaries.phone</td><td>string</td><td>Phone number of the beneficiary</td></tr><tr><td>beneficiaries.group_uid</td><td>string</td><td>Unique identifier for the beneficiary’s group</td></tr><tr><td>insured_subject</td><td>object</td><td>Details of the insured subject</td></tr><tr><td>insured_subject.identifier_value</td><td>string</td><td>Identifier of the insured subject</td></tr><tr><td>insured_subject.identifier_type</td><td>string</td><td>Type of identifier</td></tr><tr><td>insured_subject.ruc</td><td>string</td><td>Taxpayer identification number</td></tr><tr><td>insured_subject.driver_id</td><td>string</td><td>Driver's identification number</td></tr><tr><td>insured_subject.group_uid</td><td>string</td><td>Unique identifier of the insured group</td></tr><tr><td>insured_subject.group_name</td><td>string</td><td>Name of the insured group</td></tr><tr><td>insured_subject.policy_note</td><td>string</td><td>Policy coverage notes</td></tr><tr><td>insured_subject.guide_number</td><td>string</td><td>Tracking number for the shipment</td></tr><tr><td>insured_subject.plate_number</td><td>string</td><td>License plate of the transport vehicle</td></tr><tr><td>insured_subject.subject_type</td><td>string</td><td>Type of insured subject</td></tr><tr><td>insured_subject.invoice_count</td><td>number</td><td>Number of invoices related to the insured subject</td></tr><tr><td>insured_subject.departure_city</td><td>string</td><td>City of departure</td></tr><tr><td>insured_subject.departure_date</td><td>string</td><td>Departure date and time</td></tr><tr><td>insured_subject.content_category</td><td>string</td><td>Category of the transported content</td></tr><tr><td>insured_subject.departure_coords</td><td>string</td><td>GPS coordinates of departure location</td></tr><tr><td>insured_subject.destination_city</td><td>string</td><td>Destination city</td></tr><tr><td>insured_subject.driver_full_name</td><td>string</td><td>Full name of the driver</td></tr><tr><td>insured_subject.primary_category</td><td>string</td><td>Main category of insured items</td></tr><tr><td>insured_subject.business_industry</td><td>string</td><td>Industry related to the insured subject</td></tr><tr><td>insured_subject.policy_observations</td><td>string</td><td>Additional observations about the policy</td></tr><tr><td>insured_subject.total_insured_value</td><td>number</td><td>Total insured value in policy currency</td></tr><tr><td>status</td><td>string</td><td>Current status of the risk item</td></tr><tr><td>uid</td><td>string</td><td>Unique identifier</td></tr><tr><td>assets</td><td>object[]</td><td>List of associated assets</td></tr><tr><td>metadata</td><td>object</td><td>Additional structured data</td></tr><tr><td>metadata.delivery_stops</td><td>object</td><td>Details of delivery stops</td></tr><tr><td>metadata.delivery_stops.[key]</td><td>object</td><td>Delivery stop information</td></tr><tr><td>metadata.delivery_stops.[key].items</td><td>object[]</td><td>List of items delivered at this stop</td></tr><tr><td>metadata.delivery_stops.[key].items.item_sku</td><td>string</td><td>Stock-keeping unit (SKU) of the item</td></tr><tr><td>metadata.delivery_stops.[key].items.item_cost</td><td>number</td><td>Cost of the item</td></tr><tr><td>metadata.delivery_stops.[key].items.item_name</td><td>string</td><td>Name of the item</td></tr><tr><td>metadata.delivery_stops.[key].items.item_expiry</td><td>string</td><td>Expiry date of the item</td></tr><tr><td>metadata.delivery_stops.[key].items.item_quantity</td><td>number</td><td>Quantity of the item</td></tr><tr><td>metadata.delivery_stops.[key].final_coords</td><td>string</td><td>GPS coordinates of delivery stop</td></tr><tr><td>metadata.delivery_stops.[key].destination_invoice_id</td><td>string</td><td>Invoice ID for delivered items</td></tr></tbody></table>

## Get all the subscriptions

<mark style="color:blue;">`GET`</mark> `https://app.insurehero.io/api/shield/v1/subscriptions`

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

#### Query Parameters

<table><thead><tr><th>Name</th><th width="259">Type</th><th>Description</th></tr></thead><tbody><tr><td>from<mark style="color:red;">*</mark></td><td>string</td><td>Starting record index</td></tr><tr><td>to<mark style="color:red;">*</mark></td><td>string</td><td>Ending record index</td></tr></tbody></table>

#### Example response

{% tabs %}
{% tab title="200: OK Retrieved successfully" %}

```json
{
    "data": [
        {
            "id": "2849ea5e-9077-4814-a7d0-1272d77e6cb4",
            "risk_item_id": "adf98422-e8d9-4b6e-bddf-fe055f628278",
            "customer_id": "93729951-ea59-4116-a9ef-266b2f690ed4",
            "last_payment": "2024-06-19T17:49:29.137+00:00",
            "next_payment": "2024-06-23T17:49:29.137+00:00",
            "expires_at": "2025-03-31T23:59:59.999+00:00",
            "channel_id": "fc94d4a1-f834-481d-a6b2-138b823389c8",
            "interval": "day",
            "active": true,
            "interval_count": "4",
            "trial_period": "3"
        },
        {
            "id": "8a89838c-6a09-4228-b36b-0d5aeaba3f99",
            "risk_item_id": "1570ddfc-d588-4d90-b191-31c037a1563a",
            "customer_id": "93729951-ea59-4116-a9ef-266b2f690ed4",
            "last_payment": "2024-06-19T15:41:13.708+00:00",
            "next_payment": "2024-06-26T15:41:13.708+00:00",
            "expires_at": "2026-07-29T14:32:27.502+00:00",
            "channel_id": "fc94d4a1-f834-481d-a6b2-138b823389c8",
            "interval": "week",
            "active": true,
            "interval_count": "4",
            "trial_period": "0"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

#### Attributes

| Name            | Type    | Description                                                   |
| --------------- | ------- | ------------------------------------------------------------- |
| id              | uuid    | Unique identifier for the subscription.                       |
| risk\_item\_id  | uuid    | ID of the associated risk item.                               |
| customer\_id    | uuid    | ID of the customer associated with the subscription.          |
| last\_payment   | string  | Timestamp of the last payment.                                |
| next\_payment   | string  | Timestamp of the next scheduled payment.                      |
| expires\_at     | string  | Expiration date of the subscription.                          |
| channel\_id     | string  | ID of the channel through which the subscription was created. |
| interval        | string  | Frequency of the subscription.                                |
| active          | boolean | Indicates if the subscription is currently active.            |
| interval\_count | string  | Number of intervals before the next payment.                  |
| trial\_period   | string  | Trial period duration in days.                                |