Subscriptions

Endpoints

Method	Endpoint
PATCH	https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/cancel
DELETE	https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/rescission
GET	https://app.insurehero.io/api/shield/v1/subscriptions

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.

PATCH https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/cancel

Headers

Name	Type	Description
Authorization*	string	Bearer access token

Path Parameters

Name	Type	Description
riskItemId*	string	Risk item identifier

Body

Name	Type	Description
end_date*	date	End date of the Risk item. If you send "cancel" the current date is sent.

Example response

200: OK Retrieved successfully

{
    "data": {
        "id": "943511e3-de9a-4afb-a126-b434ebd1f84e",
        "policy_id": "c42a9583-9a58-4b0c-b332-21499780a35b",
        "authorized_claimants": [
            {
                "email": "[e-mail]",
                "name": "Lucia Martinez",
                "phone": "593999002823"
            },
            {
                "email": "[e-mail]",
                "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": "[e-mail]",
                "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"
                }
            }
        }
    }
}

400: Bad Request Request contains malformed data

401: Unauthorized Invalid or expired access token

402: Payment Required Pending payment

422: Unprocessable Entity Internal validation failed

429: Too Many Requests API rate limit

404: Not Found User not found

Attributes

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

Risk Item Rescission

This endpoint is useful for canceling a risk-item immediately

DELETE https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/rescission

Headers

Name	Type	Description
Authorization*	string	Bearer access token

Path Parameters

Name	Type	Description
riskItemId*	string	Risk item identifier

Example response

200: OK Retrieved successfully

{
    "data": {
        "id": "943511e3-de9a-4afb-a126-b434ebd1f84e",
        "policy_id": "c42a9583-9a58-4b0c-b332-21499780a35b",
        "authorized_claimants": [
            {
                "email": "[e-mail]",
                "name": "Lucia Martinez",
                "phone": "593999002823"
            },
            {
                "email": "[e-mail]",
                "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": "[e-mail]",
                "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"
                }
            }
        }
    }
}

Attributes

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

Get all the subscriptions

GET https://app.insurehero.io/api/shield/v1/subscriptions

Headers

Name	Type	Description
Authorization*	string	Bearer access token

Query Parameters

Name	Type	Description
from*	string	Starting record index
to*	string	Ending record index

Example response

200: OK Retrieved successfully

{
    "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"
        }
    ]
}

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.