> 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/rescissions</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><tr><td><mark style="color:blue;">GET</mark></td><td><a href="#get-a-specific-subscription"><code>https://app.insurehero.io/api/shield/v1/subscriptions/:subscriptionId</code></a></td></tr></tbody></table>

All error responses use the `{ "error": string, "details": any }` envelope. The examples on this page show the most common cases for each endpoint; see [Error Handling](https://docs.insurehero.io/shield-api/data-dictionary#error-handling) for the general format, including unexpected internal errors, which return `422` with an `event_id` you can share with support.

## Overview

Recurring charges are handled as orders. When a Risk Item uses `payment_model` `channel_billed`, its first order is created together with the Risk Item. While the Risk Item is `ACTIVE`, a process that runs every day at 06:00 UTC creates the order of each following installment, according to the billing interval configured in the package. Each installment starts with status `emitted` and `payment_status` `pending` until you report the result of the collection. See [Order management](/shield-api/policies/order-management.md).

If you create the Risk Item without `end_date` (or with `null`), it is stored with the default end date configured for your channel or, when there is none, with `2099-12-31`.

[Get all the subscriptions](#get-all-the-subscriptions) and [Get a specific subscription](#get-a-specific-subscription) return the subscriptions created by the previous billing flow. New Risk Items do not create subscriptions.

## Cancelations

To cancel a subscription, you need the ID or UID of the Risk Item to be canceled (use `?searchBy=uid` to send the UID). This allows you to terminate the subscription or modify its end date:

* If `end_date` is today (or omitted, or `"cancel"`), the Risk Item status changes to `CANCELLED` immediately and the subscription expires on that date.
* If `end_date` is a future date, only the `end_date` of the Risk Item changes; its status and the subscription do not change.
* If `end_date` is earlier than today, the request returns `422`.
* If the Risk Item is already `CANCELLED`, it is returned unchanged.

<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 (`id` by default, or its `uid`) |

#### Query Parameters

| Name     | Type   | Description                                                                                     |
| -------- | ------ | ----------------------------------------------------------------------------------------------- |
| searchBy | string | Field used to find the risk item: `id` (default) or `uid`. Use `?searchBy=uid` to send the uid. |

#### Body

| Name      | Type   | Description                                                                                                                          |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| end\_date | string | New end date of the Risk item, ISO 8601 date-time with time zone, or `"cancel"`. If omitted or `"cancel"`, the current date is used. |

The body must be a JSON object; send `{}` to cancel with the current date.

#### Example response

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

```json
{
    "data": {
        "id": "7ee10950-2b16-5718-bb99-c80eb7387cca",
        "policy_id": "9b53e9c9-17b3-5d9c-b5fd-e1780096cc8c",
        "authorized_claimants": [
            {
                "email": "lucia.martinez@example.com",
                "name": "Lucia Martinez",
                "phone": "+593991234504"
            },
            {
                "email": "marco.reyes@example.com",
                "name": "Marco Reyes",
                "phone": "+593991234505"
            }
        ],
        "package_id": "af9c0bd9-37d9-51b7-b03f-0a04c13345dd",
        "start_date": "2026-03-15T00:00:00+00:00",
        "end_date": "2026-03-20T15:02:11.381+00:00",
        "beneficiaries": [
            {
                "email": "ana.torres@example.com",
                "phone": "+593991234503"
            }
        ],
        "insured_subject": {
            "identifier_value": "GN789",
            "identifier_type": "Guide Number",
            "ruc": "1790000001001",
            "driver_id": "1700000003",
            "group_uid": "GRP-0001",
            "group_name": "Andes Logistics S.A.",
            "policy_note": "Insured against theft and damage",
            "guide_number": "GN789",
            "plate_number": "PICH1234",
            "subject_type": "cargo",
            "invoice_count": 10,
            "departure_city": "Guayaquil",
            "departure_date": "2026-03-15T09:00:00Z",
            "content_category": "Clothing",
            "departure_coords": "-2.1894, -79.8891",
            "destination_city": "Quito",
            "driver_full_name": "Luis Paredes",
            "primary_category": "Men's Apparel",
            "business_industry": "Consumer goods",
            "policy_observations": "Fragile items inside",
            "total_insured_value": 75000
        },
        "status": "CANCELLED",
        "uid": null,
        "assets": [],
        "payment_model": "included",
        "payment_status": "confirmed",
        "current_installment": 1,
        "consents": [],
        "payment": null,
        "metadata": {
            "delivery_stops": {
                "Delivery 1": {
                    "items": [
                        {
                            "item_sku": "LAP1234A",
                            "item_cost": 1200,
                            "item_name": "Laptop",
                            "item_expiry": "2026-12-31",
                            "item_quantity": 10
                        }
                    ],
                    "final_coords": "-0.1807, -78.4678",
                    "destination_invoice_id": "INV-0001"
                }
            }
        }
    }
}
```

{% endtab %}

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

```json
{
    "error": "Request contains malformed data",
    "details": "Missing bearer token"
}
```

{% endtab %}

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

```json
{
    "error": "Invalid or expired access token",
    "details": "Invalid access token"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Risk item not found" %}

```json
{
    "error": "Internal validation failed",
    "details": {
        "code": "PGRST116",
        "details": "The result contains 0 rows",
        "hint": null,
        "message": "Cannot coerce the result to a single JSON object"
    }
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Past end date" %}

```json
{
    "error": "Internal validation failed",
    "details": "end_date cannot be earlier than the current date"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid request body" %}

```json
{
    "error": "Internal validation failed",
    "details": {
        "issues": [
            {
                "code": "custom",
                "path": [
                    "body"
                ],
                "message": "Invalid request body"
            }
        ],
        "name": "ZodError"
    }
}
```

{% 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>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 | null</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 | null</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: <code>ACTIVE</code>, <code>INACTIVE</code>, <code>PENDING</code>, <code>RESCISSION</code>, <code>EXPIRED</code> or <code>CANCELLED</code></td></tr><tr><td>uid</td><td>string | null</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><tr><td>payment_model</td><td>string | null</td><td>Payment model: <code>direct</code>, <code>channel_billed</code> or <code>included</code></td></tr><tr><td>payment_status</td><td>string</td><td>Payment status: <code>pending</code>, <code>confirmed</code>, <code>failed</code>, <code>channel_due</code> or <code>cancelled</code></td></tr><tr><td>current_installment</td><td>number</td><td>Current installment number</td></tr><tr><td>consents</td><td>object[]</td><td>Consents accepted by the insured</td></tr><tr><td>payment</td><td>object | null</td><td>Payment information sent when the risk item was created</td></tr></tbody></table>

### Risk Item Rescission

This endpoint is useful for canceling a risk-item immediately. It is only allowed within the `max_rescission_window` of the policy (in minutes, counted from the creation of the Risk Item); after that window, or when the policy has no window configured, it returns `422`. A rescinded Risk Item gets status `INACTIVE` and the current date as `end_date`, its subscription expires, and its orders are cancelled.

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

#### 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 (`id` by default, or its `uid`) |

#### Query Parameters

| Name     | Type   | Description                                                                                     |
| -------- | ------ | ----------------------------------------------------------------------------------------------- |
| searchBy | string | Field used to find the risk item: `id` (default) or `uid`. Use `?searchBy=uid` to send the uid. |

#### Example response

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

```json
{
    "data": {
        "id": "7ee10950-2b16-5718-bb99-c80eb7387cca",
        "policy_id": "9b53e9c9-17b3-5d9c-b5fd-e1780096cc8c",
        "authorized_claimants": [
            {
                "email": "lucia.martinez@example.com",
                "name": "Lucia Martinez",
                "phone": "+593991234504"
            },
            {
                "email": "marco.reyes@example.com",
                "name": "Marco Reyes",
                "phone": "+593991234505"
            }
        ],
        "package_id": "af9c0bd9-37d9-51b7-b03f-0a04c13345dd",
        "start_date": "2026-03-15T00:00:00+00:00",
        "end_date": "2026-03-15T00:20:00.000+00:00",
        "beneficiaries": [
            {
                "email": "ana.torres@example.com",
                "phone": "+593991234503"
            }
        ],
        "insured_subject": {
            "identifier_value": "GN789",
            "identifier_type": "Guide Number",
            "ruc": "1790000001001",
            "driver_id": "1700000003",
            "group_uid": "GRP-0001",
            "group_name": "Andes Logistics S.A.",
            "policy_note": "Insured against theft and damage",
            "guide_number": "GN789",
            "plate_number": "PICH1234",
            "subject_type": "cargo",
            "invoice_count": 10,
            "departure_city": "Guayaquil",
            "departure_date": "2026-03-15T09:00:00Z",
            "content_category": "Clothing",
            "departure_coords": "-2.1894, -79.8891",
            "destination_city": "Quito",
            "driver_full_name": "Luis Paredes",
            "primary_category": "Men's Apparel",
            "business_industry": "Consumer goods",
            "policy_observations": "Fragile items inside",
            "total_insured_value": 75000
        },
        "status": "INACTIVE",
        "uid": null,
        "assets": [],
        "payment_model": "included",
        "payment_status": "confirmed",
        "current_installment": 1,
        "consents": [],
        "payment": null,
        "metadata": {
            "delivery_stops": {
                "Delivery 1": {
                    "items": [
                        {
                            "item_sku": "LAP1234A",
                            "item_cost": 1200,
                            "item_name": "Laptop",
                            "item_expiry": "2026-12-31",
                            "item_quantity": 10
                        }
                    ],
                    "final_coords": "-0.1807, -78.4678",
                    "destination_invoice_id": "INV-0001"
                }
            }
        }
    }
}
```

{% endtab %}

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

```json
{
    "error": "Request contains malformed data",
    "details": "Missing bearer token"
}
```

{% endtab %}

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

```json
{
    "error": "Invalid or expired access token",
    "details": "Invalid access token"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Rescission window expired" %}

```json
{
    "error": "Internal validation failed",
    "details": "The maximum rescission time has expired."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Risk item not found" %}

```json
{
    "error": "Internal validation failed",
    "details": {
        "code": "PGRST116",
        "details": "The result contains 0 rows",
        "hint": null,
        "message": "Cannot coerce the result to a single JSON object"
    }
}
```

{% 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 | null</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 | null</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: <code>ACTIVE</code>, <code>INACTIVE</code>, <code>PENDING</code>, <code>RESCISSION</code>, <code>EXPIRED</code> or <code>CANCELLED</code></td></tr><tr><td>uid</td><td>string | null</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><tr><td>payment_model</td><td>string | null</td><td>Payment model: <code>direct</code>, <code>channel_billed</code> or <code>included</code></td></tr><tr><td>payment_status</td><td>string</td><td>Payment status: <code>pending</code>, <code>confirmed</code>, <code>failed</code>, <code>channel_due</code> or <code>cancelled</code></td></tr><tr><td>current_installment</td><td>number</td><td>Current installment number</td></tr><tr><td>consents</td><td>object[]</td><td>Consents accepted by the insured</td></tr><tr><td>payment</td><td>object | null</td><td>Payment information sent when the risk item was created</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>number</td><td>Starting record index (0-based)</td></tr><tr><td>to<mark style="color:red;">*</mark></td><td>number</td><td>Ending record index (inclusive). Must be greater than <code>from</code>; the range cannot exceed 100 records</td></tr></tbody></table>

#### Example response

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

```json
{
    "data": [
        {
            "id": "74d373dd-2d5d-5f86-a0c2-5a3699e2955a",
            "risk_item_id": "bdf99865-3069-50b9-aee3-9fb2c20e2f67",
            "customer_id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
            "last_payment": "2026-06-19T17:49:29.137+00:00",
            "next_payment": "2026-06-23T17:49:29.137+00:00",
            "expires_at": "2026-12-31T23:59:59.999+00:00",
            "channel_id": "0ccad1d6-18ee-5c17-a684-9f8fe203d7c1",
            "interval": "day",
            "active": true,
            "interval_count": "4",
            "trial_period": "3"
        },
        {
            "id": "540b39f8-26cc-558c-96bd-1a5231222379",
            "risk_item_id": "7d2a8ed9-dbe4-5057-b590-eb235bf3df4d",
            "customer_id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
            "last_payment": "2026-06-19T15:41:13.708+00:00",
            "next_payment": "2026-06-26T15:41:13.708+00:00",
            "expires_at": null,
            "channel_id": "0ccad1d6-18ee-5c17-a684-9f8fe203d7c1",
            "interval": "week",
            "active": true,
            "interval_count": "4",
            "trial_period": "0"
        }
    ]
}
```

{% endtab %}

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

```json
{
    "error": "Request contains malformed data",
    "details": "Missing bearer token"
}
```

{% endtab %}

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

```json
{
    "error": "Invalid or expired access token",
    "details": "Invalid access token"
}
```

{% endtab %}

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

```json
{
    "error": "Internal validation failed",
    "details": {
        "issues": [
            {
                "code": "custom",
                "message": "Invalid range. 'from' must be less than or equal to 'to'",
                "path": []
            }
        ],
        "name": "ZodError"
    }
}
```

{% 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 \| null | Expiration date of the subscription, or `null`.               |
| channel\_id     | uuid           | 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.                                |

## Get a specific subscription

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

#### Headers

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

#### Path Parameters

| Name                                             | Type | Description                     |
| ------------------------------------------------ | ---- | ------------------------------- |
| subscriptionId<mark style="color:red;">\*</mark> | uuid | Identifier of the subscription. |

#### Example response

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

```json
{
    "data": {
        "id": "74d373dd-2d5d-5f86-a0c2-5a3699e2955a",
        "risk_item_id": "bdf99865-3069-50b9-aee3-9fb2c20e2f67",
        "customer_id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
        "last_payment": "2026-06-19T17:49:29.137+00:00",
        "next_payment": "2026-06-23T17:49:29.137+00:00",
        "expires_at": "2026-12-31T23:59:59.999+00:00",
        "channel_id": "0ccad1d6-18ee-5c17-a684-9f8fe203d7c1",
        "interval": "day",
        "active": true,
        "interval_count": "4",
        "trial_period": "3"
    }
}
```

{% endtab %}

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

```json
{
    "error": "Request contains malformed data",
    "details": "Missing bearer token"
}
```

{% endtab %}

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

```json
{
    "error": "Invalid or expired access token",
    "details": "Invalid access token"
}
```

{% endtab %}

{% tab title="404: Not Found Resource not found" %}
The subscription does not exist in your channel, or the id is not a valid uuid:

```json
{
    "error": "Resource not found",
    "details": "Coverage not found"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Internal validation failed" %}
Internal error. See [Error Handling](https://docs.insurehero.io/shield-api/data-dictionary#error-handling).
{% endtab %}
{% endtabs %}

#### Attributes

Same fields as in [Get all the subscriptions](#get-all-the-subscriptions), in a single object in `data`.