> 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/order-management.md).
# Order management
Orders are the charges of a risk item. Each one belongs to a risk item and keeps its price breakdown, its payment data and its payment status.
How the first order of a risk item starts depends on its `payment_model`:
* `direct`: the payment was already collected, so the order is created with status `confirmed`.
* `channel_billed`: your channel collects the payment, so the order is created with status `emitted` and `payment_status` `pending`. Report the result of each collection with [Report the result of a payment](#report-the-result-of-a-payment).
## Endpoints
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.
### Get the orders of your channel
`GET` `https://app.insurehero.io/api/shield/v1/orders`
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization\* | string | Bearer access token |
#### Query Params
| Name | Type | Description |
| --------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| start\_date\* | string | Returns the orders created on or after this date. ISO 8601 date or date-time. |
| end\_date\* | string | Returns the orders created up to the end of this day (UTC). It cannot be earlier than `start_date` or more than 6 months after it. |
| status | string | Returns only the orders with this status: `emitted`, `confirmed`, `failed`, `returned`, `cancelled`, `scheduled`, `rehabilitated` or `adjustment`. |
| from | number | Position of the first order to return, starting at `0`. Send it together with `to`. |
| to | number | Position of the last order to return, inclusive. Send it together with `from`; it cannot be lower than `from`. |
#### Example Response
Returns the orders of your channel created between `start_date` and `end_date`. The number of orders per response is limited, so use `from` and `to` to page through large ranges.
{% tabs %}
{% tab title="200: OK Retrieved successfully" %}
```json
{
"data": [
{
"id": "2437ecb7-787e-5bdd-8e29-8eed1ec1283a",
"channel_id": "0ccad1d6-18ee-5c17-a684-9f8fe203d7c1",
"risk_item_id": "a5d121c4-71d1-53a8-ac60-f7af4c368d2a",
"customer_id": null,
"customer_data": {},
"status": "emitted",
"created_at": "2026-10-12T20:59:47.746811+00:00",
"status_data": {},
"channel_taxes": null,
"insurer_taxes": null,
"insurer_net_price": null,
"insurer_gross_price": null,
"platform_taxes": null,
"platform_net_price": null,
"platform_gross_price": null,
"channel_gross_price": null,
"total_taxes": null,
"total_net_price": null,
"total_gross_price": "2670",
"payment_type": "channel_monthly_billing",
"payment_status": "pending",
"installment_number": 1,
"installments_total": null,
"effective_date": "2026-10-12T20:59:47.354+00:00",
"expiry_date": "2026-11-11T20:59:47.354+00:00",
"paid_date": null,
"payment_attempts": 0,
"pricing": {
"currency": "USD",
"coverages": [
{
"uid": "COV-MEDICAL",
"name": "Telemedicine",
"cod_cob": "COV-MEDICAL-01",
"gross_price": 2670,
"net_price": 2243.6975,
"taxes": 426.3025,
"markups": 0.03,
"taxes_details": [
{
"name": "VAT",
"rate": 0.19,
"amount": 426.3025
}
],
"markups_details": [
{
"owner": "insurer",
"gross_price": 0.19,
"net_price": 0.16,
"details": [
{
"name": "VAT",
"rate": 0.19,
"amount": 0.03
}
]
}
]
}
],
"total": {
"gross_price": 2670,
"net_price": 2243.6975,
"taxes": 426.3025,
"markups": 0.03,
"taxes_details": [
{
"name": "VAT",
"amount": 426.3025
}
],
"markups_details": [
{
"owner": "insurer",
"gross_price": 0.19,
"net_price": 0.16,
"details": [
{
"name": "VAT",
"amount": 0.03
}
]
}
]
},
"discount": {
"gross_price": 0,
"net_price": 0,
"taxes": 0,
"taxes_details": []
}
},
"payment": {
"source": "risk_item_activation",
"transaction": null,
"processor": null,
"installment": {
"number": 1,
"total_installments": null
},
"carrier": {},
"context": {
"channel_order_id": "SALE-0001",
"sale_origin": "api",
"sale_timestamp": "2026-10-12T20:59:47.734Z"
}
},
"external_id": 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="422: Unprocessable Entity Internal validation failed" %}
A range longer than 6 months:
```json
{
"error": "Internal validation failed",
"details": {
"issues": [
{
"code": "custom",
"path": ["searchParams", "end_date"],
"message": "Invalid range, cannot exceed 6 months"
}
],
"name": "ZodError"
}
}
```
Other messages: `"Invalid range. 'start_date' must be less than or equal to 'end_date'"`, `"Both 'from' and 'to' are required for pagination"` and `"Invalid pagination. 'from' must be less than or equal to 'to'"`. A missing date or an unknown `status` returns the same kind of error.
{% endtab %}
{% endtabs %}
#### Attributes
| Name | Type | Description |
| ---------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| data | object \[] | List of orders. Each item has the following fields. |
| id | uuid | Unique identifier for the order. |
| channel\_id | uuid | Identifier of the channel of the order. |
| risk\_item\_id | uuid | Identifier of the associated risk item. Can be `null`. |
| customer\_id | uuid | Identifier of the customer. Can be `null`. |
| customer\_data | object | Customer information. |
| status | string | Status of the order: `emitted`, `confirmed`, `failed`, `returned`, `cancelled`, `scheduled`, `rehabilitated` or `adjustment`. |
| created\_at | string | Date and time when the order was created. |
| status\_data | object | Additional status-related metadata. Can be `null`. |
| channel\_taxes | string | Amount of channel taxes applied to the order. Can be `null`. |
| channel\_gross\_price | string | Gross price from the channel. Can be `null`. |
| platform\_taxes | string | Amount of platform taxes applied to the order. Can be `null`. |
| platform\_net\_price | string | Net price from the platform. Can be `null`. |
| platform\_gross\_price | string | Gross price from the platform. Can be `null`. |
| insurer\_taxes | string | Amount of insurer taxes applied to the order. Can be `null`. |
| insurer\_net\_price | string | Net price from the insurer. Can be `null`. |
| insurer\_gross\_price | string | Gross price from the insurer. Can be `null`. |
| total\_taxes | string | Total amount of taxes applied to the order. Can be `null`. |
| total\_net\_price | string | Total net price of the order. Can be `null`. |
| total\_gross\_price | string | Total gross price of the order. Can be `null`. |
| payment\_type | string | Payment type: `direct_card`, `bank_transfer`, `channel_monthly_billing`, `end_of_month`, `domiciliation` or `single_premium`. Can be `null`. |
| payment\_status | string | Payment status of the order: `pending`, `confirmed`, `failed`, `returned`, `cancelled` or `rehabilitated`. Can be `null`. |
| installment\_number | number | Installment number of the order. |
| installments\_total | number | Total number of installments. Can be `null`. |
| effective\_date | string | Date when the order takes effect. Can be `null`. |
| expiry\_date | string | Date when the order expires. Can be `null`. |
| paid\_date | string | Date when the order was paid. Can be `null`. |
| payment\_attempts | number | Number of payment attempts. |
| pricing | object | Price breakdown of the order. Can be `{}` or `null`. Same fields as in [Fetch Orders](/shield-api/integrations/fetch-orders.md#pricing). |
| payment | object | Payment details of the order. Can be `{}` or `null`. Same fields as in [Fetch Orders](/shield-api/integrations/fetch-orders.md#payment). |
| external\_id | number | Numeric order number. Once assigned, it does not change. |
### Report the result of a payment
`PATCH` `https://app.insurehero.io/api/shield/v1/orders/:orderId/payment-result`
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization\* | string | Bearer access token |
#### Path Parameters
| Name | Type | Description |
| ----------------------------------------- | ---- | ------------------------ |
| orderId\* | uuid | Identifier of the order. |
#### Request Body
| Name | Type | Description |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------- |
| result\* | string | `ok` when the payment was collected, `ko` when it failed. |
| processed\_at\* | string | Date and time when the payment was processed, ISO 8601 in UTC (for example `2026-10-12T21:00:14.047Z`). |
| reason | string | Reason of the result, for example the rejection reason. |
| metadata | object | Additional data about the payment. |
```json
{
"result": "ko",
"processed_at": "2026-10-12T21:00:14.047Z",
"reason": "insufficient funds",
"metadata": {
"collection_id": "COL-0001"
}
}
```
#### Example Response
Only orders with status `emitted` or `failed` accept a result:
* `ok`: the order becomes `confirmed`, with `payment_status` `confirmed` and `processed_at` as `paid_date`.
* `ko`: the order gets `payment_status` `failed` and one more `payment_attempts`. When the risk item then has two or more orders pending payment (`emitted` or `failed`), those orders and the risk item are cancelled. When the order reaches two failed attempts, the order is cancelled, and so is the risk item if it has no other active orders. In both cases `cascadedToRiskItem` tells you whether the risk item was cancelled.
Sending the same `result` again with the same `processed_at` does not change anything and returns `noop: true`, so you can safely retry a request.
{% tabs %}
{% tab title="200: OK Result registered" %}
```json
{
"data": {
"noop": false,
"cascadedToRiskItem": false,
"eventId": "3eecd7d4-d064-5315-909f-99fe8ad2de43"
}
}
```
A repeated request:
```json
{
"data": {
"noop": true,
"cascadedToRiskItem": false,
"eventId": null
}
}
```
{% 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 order does not exist in your channel:
```json
{
"error": "Resource not found",
"details": "Order not found"
}
```
{% endtab %}
{% tab title="409: Conflict Invalid order transition" %}
The order does not accept the result, for example because it is already confirmed or cancelled. `details` includes the current state of the order:
```json
{
"error": "Invalid order transition",
"details": {
"orderId": "2437ecb7-787e-5bdd-8e29-8eed1ec1283a",
"fromState": {
"status": "confirmed",
"payment_status": "confirmed",
"payment_attempts": 0,
"paid_date": "2026-10-12T21:00:14.047+00:00"
},
"attempted": "payment_confirmed",
"detail": "order is already confirmed"
}
}
```
`attempted` is `payment_confirmed` for `ok` and `payment_failed` for `ko`. `detail` can be `"order is already confirmed"`, `"order is cancelled"` or `"unexpected status "`.
{% endtab %}
{% tab title="422: Unprocessable Entity Internal validation failed" %}
Invalid input:
```json
{
"error": "Internal validation failed",
"details": {
"issues": [
{
"received": "maybe",
"code": "invalid_enum_value",
"options": ["ok", "ko"],
"path": ["body", "result"],
"message": "Invalid enum value. Expected 'ok' | 'ko', received 'maybe'"
},
{
"code": "invalid_string",
"validation": "datetime",
"message": "Invalid datetime",
"path": ["body", "processed_at"]
}
],
"name": "ZodError"
}
}
```
An `orderId` that is not a uuid or a body that is not valid JSON returns the same kind of error.
{% endtab %}
{% endtabs %}
#### Attributes
| Name | Type | Description |
| ------------------ | ------- | ---------------------------------------------------------------------------------------------------- |
| data | object | Result of the request. |
| noop | boolean | `true` when the same result was already registered with the same `processed_at` and nothing changed. |
| cascadedToRiskItem | boolean | `true` when the result cancelled the risk item. |
| eventId | string | Identifier of the registered payment event. `null` when `noop` is `true`. |
To access these resources, please remember to visit the [**Links and Resources**](/shield-api/links-and-resources.md) section of the documentation.