Core API
The Carriyo Core API manages shared reference data used across the Shipping, Returns, and Orders APIs: delivery types, order types, time slots, locations, webhooks, and custom attributes.
Delivery types, locations, order types, time slots, webhooks, and custom attributes are configuration you set up once and change infrequently. For most merchants it’s one-time onboarding plus occasional changes. Consider using the Carriyo Dashboard instead: it validates inputs, surfaces required fields contextually, and protects you from the most common misconfigurations.
See the Guides section for step-by-step setup guides.
Delivery Types
A delivery type is the kind of delivery service the customer chose, such as "Same Day", "Next Day" or "International", identified by a code you supply; Carriyo derives delivery_type_id from it. A delivery type cannot be changed after creation, and deleting one is permanent. Reading an unknown delivery_type_id answers 200 with an empty body; deleting one answers 400.
4 operations · 0 objects
/delivery-typesCreate delivery type
Creates a delivery type under the code you supply.
Behavior
A delivery type cannot be changed after creation; to change one, delete it and create it again.
Errors
400—codeis missing.400—codeis longer than 250 characters.400— a delivery type with thiscodealready exists.
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
Request body
application/jsonSchema: delivery-type-requestResponses
delivery-type-responseerror-responseNeed the full machine-readable spec? Download the OpenAPI document →
/delivery-typesList delivery types
Returns all of the tenant's delivery types in a single unpaged array.
Behavior
The response is sent with Cache-Control: max-age=3600, private, stale-while-revalidate=86400, so a caching client or proxy may keep serving it for up to an hour after a delivery type is created or deleted, and a stale copy for a further 24 hours while it revalidates.
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
An array of delivery-type-response. Each item has the following fields:
Need the full machine-readable spec? Download the OpenAPI document →
/delivery-types/{delivery-type-id}Get delivery type
Returns the delivery type with this delivery_type_id.
Behavior
An unknown delivery_type_id is not an error: the call answers 200 with an empty body, so check for a body before parsing.
Errors
200with an empty body — no delivery type has thisdelivery_type_id.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| delivery-type-id | string | Yes | The `delivery_type_id` returned by create or list, not the bare `code`. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
delivery-type-responseNeed the full machine-readable spec? Download the OpenAPI document →
/delivery-types/{delivery-type-id}Delete delivery type
Permanently deletes the delivery type with this delivery_type_id. This cannot be undone.
Behavior
The delivery type is removed from any Shopify or WooCommerce connector mapping that references it. Rules are not changed: the delete is refused while an automation, service-level, shipment-costing or capacity rule references the delivery type.
Errors
400— an automation, service-level, shipment-costing or capacity rule still references the delivery type.400— no delivery type has thisdelivery_type_id.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| delivery-type-id | string | Yes | The `delivery_type_id` returned by create or list, not the bare `code`. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
error-responseNeed the full machine-readable spec? Download the OpenAPI document →
Locations
A location is a merchant address, usually a store or warehouse, that ships, holds stock, or hands over goods to customers; it has a location_code you supply, a location_name, an address and the merchants that may use it, and is referenced by shipments, orders and return requests. Carriyo assigns location_id. A location can be replaced or patched, and deleting one is soft: status becomes DELETED, the id stays readable, and the location leaves the list. Reading an unknown location_id answers 200 with an empty body; updating or deleting one answers 400.
7 operations · 0 objects
/locationsCreate location
Creates a location and assigns its location_id.
Behavior
What to send. Each of these rules is checked before the location is stored:
location_codemust be unique among non-deleted locations.location_namemust be unique too, unless your tenant has that check disabled.merchantsnames the merchants that may use the location;"_ANY"grants every merchant, and an empty list is rejected.address1must be present.stateis required for addresses in US, CA and PH.fulfillment_zonesandfulfillment_radiusare mutually exclusive; a radius needscoordsand a value greater than 0, zones need neither.
Status. status defaults to ACTIVE when omitted.
Limits. Two limits apply. The total number of non-deleted locations may not exceed your plan's location limit plus a buffer of 100; a request beyond it is rejected. A request that would exceed the plan's ACTIVE limit is stored INACTIVE rather than rejected, so check status in the response.
Errors
400—location_codeis already used by a non-deleted location.400—location_nameis already in use.400—merchantsis empty.400—address1is empty.400—stateis missing for a US, CA or PH address.400— bothfulfillment_zonesandfulfillment_radiusare set.400—fulfillment_radiusis set withoutcoords, or its value is not greater than 0.400— the tenant has reached its total location limit.
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
Request body
application/jsonSchema: location-requestResponses
location-responseerror-responseNeed the full machine-readable spec? Download the OpenAPI document →
/locationsList locations
Returns the tenant's locations a page at a time; page is zero-based.
Behavior
Paging and sorting. page_size * (page + 1) may not exceed 10,000, so the list reaches at most the first 10,000 locations. pagination in the response carries total and page only. Sorting is ignored when search_string is set.
Filtering. Results are limited to the merchants the API key can access. DELETED locations are excluded unless show_deleted=true, so status=DELETED on its own returns nothing.
Response. Items come from the search index and carry fields (geo_coords, tenant, test_data, updated_by_user) that the single-location read does not, alongside your custom location attributes in custom_attributes. cache sets Cache-Control: max-age on the response to that many seconds.
Errors
400—page_sizeis above 100.400—page_size * (page + 1)is above 10,000.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
| page | integer | No | Page to return, starting at 0. `page_size * (page + 1)` must not exceed 10,000. |
| page_size | integer | No | Records per page, 0 to 100. |
| sort_by | string | No | Field to sort by, such as `location_name`, `location_code`, `city`, `country`, `status` or `location_type`. Ignored when `search_string` is set. |
| sort_direction | string | No | Sort order for `sort_by`. |
| search_string | string | No | Free-text search over `location_name`, `location_code`, `contact_name` and `company_name`. Results are ranked by relevance and `sort_by` is ignored. |
| status | array | No | Return only locations in these statuses. Repeatable; values are upper-cased. `DELETED` matches nothing unless `show_deleted` is `true`. |
| show_deleted | boolean | No | Include `DELETED` locations, which are otherwise excluded whatever `status` says. |
| location_access | array | No | Restrict results to these location ids. Repeatable; combined with `country_access`, a location matches when it satisfies either. |
| country_access | array | No | Restrict results to these two-letter country codes. Repeatable. |
| creation_date_from | string | No | Return only locations created on or after this date, interpreted in the `tzoffset` timezone. |
| creation_date_to | string | No | Return only locations created on or before this date, interpreted in the `tzoffset` timezone. |
| tzoffset | integer | No | Offset from UTC in minutes applied to the date filters. |
| cache | integer | No | When set, the response carries `Cache-Control: private, max-age=<cache>` with this many seconds. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
location-listerror-responseNeed the full machine-readable spec? Download the OpenAPI document →
/locations/{location-id}Get location
Returns the location with this location_id.
Behavior
A deleted location is still returned, with status set to DELETED. An unknown location_id is not an error: the call answers 200 with an empty body, so check for a body before parsing.
Errors
200with an empty body — no location has thislocation_id.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| location-id | string | Yes | The `location_id` returned by create or list. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
location-responseNeed the full machine-readable spec? Download the OpenAPI document →
/locations/{location-id}Update location
Replaces the location with this location_id with the request body.
Behavior
What happens. Every field is set to the value supplied; a field omitted from the request is cleared. Only location_id, creation_date, creation_source and the test-data flag are kept from the stored location.
What to send. Create's rules apply to the replacement:
location_codemust be unique among non-deleted locations.location_namemust be unique too, unless your tenant has that check disabled.merchantsnames the merchants that may use the location;"_ANY"grants every merchant, and an empty list is rejected.address1must be present.stateis required for addresses in US, CA and PH.fulfillment_zonesandfulfillment_radiusare mutually exclusive; a radius needscoordsand a value greater than 0, zones need neither.
Status. The ACTIVE limit applies when the request would make the location ACTIVE: the update is refused, not silently stored INACTIVE as on create.
Errors
400—location_codeis already used by a non-deleted location.400—location_nameis already in use.400—merchantsis empty.400—address1is empty.400—stateis missing for a US, CA or PH address.400— bothfulfillment_zonesandfulfillment_radiusare set.400—fulfillment_radiusis set withoutcoords, or its value is not greater than 0.400— the update would exceed the number ofACTIVElocations allowed.400— no location has thislocation_id.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| location-id | string | Yes | The `location_id` returned by create or list. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
Request body
application/jsonSchema: location-requestResponses
location-responseerror-responseNeed the full machine-readable spec? Download the OpenAPI document →
/locations/{location-id}Partially update location
Partially updates the location with this location_id.
Behavior
What happens. Only the fields present in the request are changed, so a patch cannot clear a field, with one exception: a patch that omits status is applied as status: ACTIVE, so patching an INACTIVE location without status reactivates it. List fields (merchants, address_codes, custom_fields, custom_attributes, fulfillment_zones) are replaced wholesale rather than merged. A non-empty fulfillment_zones clears fulfillment_radius, and a fulfillment_radius clears fulfillment_zones.
What to send. Create's uniqueness and validation rules apply to the merged result, so a patch that would leave the location with a duplicate location_code, an empty address1, or both fulfillment_zones and fulfillment_radius is rejected.
Status. Send status: INACTIVE explicitly to keep an inactive location inactive. Setting status to ACTIVE is refused when the tenant is already at its ACTIVE limit.
Errors
400— the merged location breaks one of create's rules.400— the update would exceed the number ofACTIVElocations allowed.400— no location has thislocation_id.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| location-id | string | Yes | The `location_id` returned by create or list. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
Request body
application/jsonSchema: patch-location-requestResponses
location-responseerror-responseNeed the full machine-readable spec? Download the OpenAPI document →
/locations/{location-id}Delete location
Deletes the location with this location_id by setting its status to DELETED.
Behavior
The location keeps its location_id and is still returned by the single-location read, but it leaves the list unless show_deleted=true. Orders and reservations that reference it are not changed. Rules are not changed either: the delete is refused while an automation, service-level, shipment-costing or capacity rule references the location.
Errors
400— an automation, service-level, shipment-costing or capacity rule still references the location.400— no location has thislocation_id.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| location-id | string | Yes | The `location_id` returned by create or list. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
error-responseNeed the full machine-readable spec? Download the OpenAPI document →
/locations/bulk/importBulk import locations
Creates or updates up to 20 locations in one request.
Behavior
What to send. location_requests holds one entry per location, each in the shape of the create request. Entries are matched by location_code: an existing code is updated, a new code is created.
What happens. Rows are processed independently, so one rejected row does not fail the others. Duplicate location_code or location_name values within the request reject those rows. Two limits are computed once before processing: rows beyond the total location limit are rejected, and rows that would exceed the ACTIVE limit are created INACTIVE rather than rejected.
Response. A bare list with one entry per input row, in no guaranteed order; match rows by locationCode (note the camelCase key), which echoes the code from the request. result is created, updated or rejected; reason explains a rejection; location is the saved location when the row was not rejected.
Errors
400—location_requestsis empty.400— more than 20 entries inlocation_requests.
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
Request body
application/jsonSchema: location-bulk-import-requestrequiredResponses
An array of location-bulk-import-response. Each item has the following fields:
error-responseNeed the full machine-readable spec? Download the OpenAPI document →
Order Types
An order type is the order journey the customer chose, such as "Home Delivery" or "Click & Collect", identified by a code you supply; Carriyo derives order_type_id from it. An order type cannot be changed after creation, and deleting one is permanent. Reading an unknown order_type_id answers 200 with an empty body; deleting one answers 400.
4 operations · 0 objects
/order-typesCreate order type
Creates an order type under the code you supply.
Behavior
An order type cannot be changed after creation; to change one, delete it and create it again.
Errors
400—codeis missing.400—codeis longer than 250 characters.400— an order type with thiscodealready exists.
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
Request body
application/jsonSchema: order-type-requestResponses
order-type-responseerror-responseNeed the full machine-readable spec? Download the OpenAPI document →
/order-typesList order types
Returns all of the tenant's order types in a single unpaged array, ordered by code.
Behavior
The response is sent with Cache-Control: max-age=3600, private, stale-while-revalidate=86400, so a caching client or proxy may keep serving it for up to an hour after an order type is created or deleted, and a stale copy for a further 24 hours while it revalidates.
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
An array of order-type-response. Each item has the following fields:
Need the full machine-readable spec? Download the OpenAPI document →
/order-types/{order-type-id}Get order type
Returns the order type with this order_type_id.
Behavior
An unknown order_type_id is not an error: the call answers 200 with an empty body, so check for a body before parsing.
Errors
200with an empty body — no order type has thisorder_type_id.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| order-type-id | string | Yes | The `order_type_id` returned by create or list, not the bare `code`. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
order-type-responseNeed the full machine-readable spec? Download the OpenAPI document →
/order-types/{order-type-id}Delete order type
Permanently deletes the order type with this order_type_id. This cannot be undone.
Behavior
No connector mapping is touched. Rules are not changed: the delete is refused while an automation, service-level, shipment-costing or capacity rule references the order type.
Errors
400— an automation, service-level, shipment-costing or capacity rule still references the order type.400— no order type has thisorder_type_id.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| order-type-id | string | Yes | The `order_type_id` returned by create or list, not the bare `code`. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
error-responseNeed the full machine-readable spec? Download the OpenAPI document →
Time Slots
A time slot is a window with a from and to time and an optional name that can be offered to the customer for a collection or a delivery when creating a shipment or a return request. time_slot_id is supplied by you and cannot be changed after creation, and deleting a time slot is permanent. An unknown time_slot_id answers 404 on read and delete.
4 operations · 0 objects
/time-slotsCreate time slot
Creates a time slot under the time_slot_id you supply.
Behavior
time_slot_id must be unique, and to must be later than from. A time slot cannot be changed after creation; to change one, delete it and create it again.
Errors
400—time_slot_idalready exists.400—tois not later thanfrom.
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
Request body
application/jsonSchema: time-slotResponses
time-sloterror-responseNeed the full machine-readable spec? Download the OpenAPI document →
/time-slotsList time slots
Returns all of the tenant's time slots in a single unpaged array.
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
An array of time-slot. Each item has the following fields:
Need the full machine-readable spec? Download the OpenAPI document →
/time-slots/{time-slot-id}Get time slot
Returns the time slot with this time_slot_id.
Errors
404— no time slot has thistime_slot_id.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| time-slot-id | string | Yes | The `time_slot_id` you supplied on create. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
time-sloterror-responseNeed the full machine-readable spec? Download the OpenAPI document →
/time-slots/{time-slot-id}Delete time slot
Permanently deletes the time slot with this time_slot_id. This cannot be undone.
Behavior
No rule references a time slot, so the delete is never refused on that ground.
Errors
404— no time slot has thistime_slot_id.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| time-slot-id | string | Yes | The `time_slot_id` you supplied on create. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
error-responseNeed the full machine-readable spec? Download the OpenAPI document →
Delivery Options
A delivery option is a customer-facing delivery choice, such as "Same Day" or "Next Day Premium", shown on your webstore or app; it carries the carrier account that fulfills it, its shipping_fee, its delivery_estimation, and the eligibility conditions (geography, order value, weight, payment type, product categories) under which it is offered. It is configured here and evaluated for shoppers by the Storefront API. Carriyo assigns id; an option can be replaced, and deleting one is permanent. An unknown id answers 404 on read, update and delete.
5 operations · 0 objects
/delivery-optionsCreate delivery option
Creates a delivery option with its carrier account, schedule, fee and eligibility conditions, and assigns its id.
Behavior
What to send. code, name, delivery_method, status and merchant are required; status has no default. code must be unique within the tenant.
Silent adjustments. PAID is the ordinary shipping_fee.pricing_strategy and is stored as sent; Carriyo adjusts the following on save without reporting it, so read the response rather than assuming the request was stored as sent:
- a
shipping_fee.pricing_strategyofPASS_THROUGHwith nocarrier_account_idis stored asFREE_OF_COSTwith the pricing cleared. delivery_method: DIGITALclearscarrier_account_id.- any
delivery_methodother thanCOLLECTIONclearscustomer_collection_locationsandcustomer_collection_max_distance.
Status. status is stored exactly as sent; DELETED and REDACTED are accepted like any other value and are not treated specially.
Errors
400—code,name,delivery_method,statusormerchantis missing.400—codealready exists in the tenant.
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
Request body
application/jsonSchema: delivery-optionrequired- Order-level category condition: shows or hides the option for the whole order. The option is offered only when at least one item in the order has an
includescategory, and withheld when any item has anexcludescategory. To scope the option per item instead, useitem_product_categories. - Item-level category condition: scopes the option per item instead of showing or hiding it for the whole order. With
includes, the option applies only to items whose category is listed; withexcludes, items with a listed category are excluded and every other item qualifies. Non-matching items are marked unavailable for the option in storefront delivery-options responses (availability: NONE,fulfillable_quantity: 0), and an option no cart item matches is not returned. An item with no category fails a non-emptyincludeslist and passes an excludes-only condition. Matching is case-insensitive and ignores surrounding whitespace. - For
COLLECTIONmethods: IDs of the Carriyo locations the customer can collect from. Only locations with thecollection_locationflag enabled are accepted. An empty or omitted list means any location: at storefront read time the option resolves to everyACTIVEcollection-enabled location the merchant can use, restricted to the customer's country. An explicit list is honored as-is — it is not filtered by the customer's country, so a merchant can deliberately include cross-border collection points (unlike the any-location behaviour, which is always same-country). - For
COLLECTIONmethods: maximum distance from the customer to a candidate collection location. Enforced only when the storefront request supplies the customer's coordinates — it is a proximity bound, not a country bound, so a radius near a border can legitimately include cross-border locations from an explicit list.
Responses
delivery-option- Order-level category condition: shows or hides the option for the whole order. The option is offered only when at least one item in the order has an
includescategory, and withheld when any item has anexcludescategory. To scope the option per item instead, useitem_product_categories. - Item-level category condition: scopes the option per item instead of showing or hiding it for the whole order. With
includes, the option applies only to items whose category is listed; withexcludes, items with a listed category are excluded and every other item qualifies. Non-matching items are marked unavailable for the option in storefront delivery-options responses (availability: NONE,fulfillable_quantity: 0), and an option no cart item matches is not returned. An item with no category fails a non-emptyincludeslist and passes an excludes-only condition. Matching is case-insensitive and ignores surrounding whitespace. - For
COLLECTIONmethods: IDs of the Carriyo locations the customer can collect from. Only locations with thecollection_locationflag enabled are accepted. An empty or omitted list means any location: at storefront read time the option resolves to everyACTIVEcollection-enabled location the merchant can use, restricted to the customer's country. An explicit list is honored as-is — it is not filtered by the customer's country, so a merchant can deliberately include cross-border collection points (unlike the any-location behaviour, which is always same-country). - For
COLLECTIONmethods: maximum distance from the customer to a candidate collection location. Enforced only when the storefront request supplies the customer's coordinates — it is a proximity bound, not a country bound, so a radius near a border can legitimately include cross-border locations from an explicit list.
error-responseNeed the full machine-readable spec? Download the OpenAPI document →
/delivery-optionsList delivery options
Returns the tenant's delivery options a page at a time; page is 1-based.
Behavior
Parameters. This list's query parameters are camelCase (pageSize, carrierAccountIds, locationIds, customerCountry, searchString), unlike the location list. The pagination parameter is a flag; the pagination object in the response reports the page position.
Paging. pageSize defaults to 10 with no maximum, and an out-of-range page returns an empty list. With pagination=false the whole filtered set comes back unpaged, and the response reports page 0 and page_size 0 with the real total. Options come back in storage order; there is no sequence field to order them by.
The 100-option ceiling. Only the first 100 stored options are read, and every filter, total and the paging operate on that slice, so an account with more than 100 options cannot reach the rest through this list.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
| page | integer | No | Page to return, starting at 1. An out-of-range page returns an empty list. |
| pageSize | integer | No | Records per page, with no maximum. Named in camelCase; the response echoes it as `page_size`. |
| pagination | boolean | No | Set to `false` to return the whole filtered set unpaged; the response then reports `page` 0 and `page_size` 0 with the real `total`. |
| merchant | string | No | Return only options whose `merchant` is exactly this value; options with merchant `_ANY` always pass. |
| status | array | No | Return only options in any of these statuses. Repeatable; exact match. |
| carrierAccountIds | array | No | Return only options whose `carrier_account_id` is exactly one of these values. |
| locationIds | array | No | Return only options whose `fulfillment_locations` or `customer_collection_locations` include at least one of these location ids. |
| customerCountry | string | No | Return only options whose `customer` condition explicitly lists this country (ISO 3166-1 alpha-2). An option with no `customer` condition is excluded. |
| searchString | string | No | Case-insensitive contains match on `name` and `code`. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
Need the full machine-readable spec? Download the OpenAPI document →
/delivery-options/{delivery-option-id}Get delivery option
Returns the delivery option with this id.
Errors
404— no delivery option has thisid.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| delivery-option-id | string | Yes | The `id` returned by create or list. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
delivery-option- Order-level category condition: shows or hides the option for the whole order. The option is offered only when at least one item in the order has an
includescategory, and withheld when any item has anexcludescategory. To scope the option per item instead, useitem_product_categories. - Item-level category condition: scopes the option per item instead of showing or hiding it for the whole order. With
includes, the option applies only to items whose category is listed; withexcludes, items with a listed category are excluded and every other item qualifies. Non-matching items are marked unavailable for the option in storefront delivery-options responses (availability: NONE,fulfillable_quantity: 0), and an option no cart item matches is not returned. An item with no category fails a non-emptyincludeslist and passes an excludes-only condition. Matching is case-insensitive and ignores surrounding whitespace. - For
COLLECTIONmethods: IDs of the Carriyo locations the customer can collect from. Only locations with thecollection_locationflag enabled are accepted. An empty or omitted list means any location: at storefront read time the option resolves to everyACTIVEcollection-enabled location the merchant can use, restricted to the customer's country. An explicit list is honored as-is — it is not filtered by the customer's country, so a merchant can deliberately include cross-border collection points (unlike the any-location behaviour, which is always same-country). - For
COLLECTIONmethods: maximum distance from the customer to a candidate collection location. Enforced only when the storefront request supplies the customer's coordinates — it is a proximity bound, not a country bound, so a radius near a border can legitimately include cross-border locations from an explicit list.
error-responseNeed the full machine-readable spec? Download the OpenAPI document →
/delivery-options/{delivery-option-id}Update delivery option
Replaces the delivery option with this id with the request body.
Behavior
What happens. Every field is set to the value supplied; a field omitted from the request is cleared. Only id, the tenant and creation_date are kept from the stored option.
Silent adjustments. PAID is the ordinary shipping_fee.pricing_strategy and is stored as sent; Carriyo adjusts the following on save without reporting it, so read the response rather than assuming the request was stored as sent:
- a
shipping_fee.pricing_strategyofPASS_THROUGHwith nocarrier_account_idis stored asFREE_OF_COSTwith the pricing cleared. delivery_method: DIGITALclearscarrier_account_id.- any
delivery_methodother thanCOLLECTIONclearscustomer_collection_locationsandcustomer_collection_max_distance.
Status. status is stored exactly as sent; DELETED and REDACTED are accepted like any other value and are not treated specially.
Code. Uniqueness is checked only when code changes by more than its case; a case-only rename is not checked and can leave two options with the same code.
Errors
400—codeis changed to one that already exists in the tenant.404— no delivery option has thisid.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| delivery-option-id | string | Yes | The `id` returned by create or list. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
Request body
application/jsonSchema: delivery-optionrequired- Order-level category condition: shows or hides the option for the whole order. The option is offered only when at least one item in the order has an
includescategory, and withheld when any item has anexcludescategory. To scope the option per item instead, useitem_product_categories. - Item-level category condition: scopes the option per item instead of showing or hiding it for the whole order. With
includes, the option applies only to items whose category is listed; withexcludes, items with a listed category are excluded and every other item qualifies. Non-matching items are marked unavailable for the option in storefront delivery-options responses (availability: NONE,fulfillable_quantity: 0), and an option no cart item matches is not returned. An item with no category fails a non-emptyincludeslist and passes an excludes-only condition. Matching is case-insensitive and ignores surrounding whitespace. - For
COLLECTIONmethods: IDs of the Carriyo locations the customer can collect from. Only locations with thecollection_locationflag enabled are accepted. An empty or omitted list means any location: at storefront read time the option resolves to everyACTIVEcollection-enabled location the merchant can use, restricted to the customer's country. An explicit list is honored as-is — it is not filtered by the customer's country, so a merchant can deliberately include cross-border collection points (unlike the any-location behaviour, which is always same-country). - For
COLLECTIONmethods: maximum distance from the customer to a candidate collection location. Enforced only when the storefront request supplies the customer's coordinates — it is a proximity bound, not a country bound, so a radius near a border can legitimately include cross-border locations from an explicit list.
Responses
delivery-option- Order-level category condition: shows or hides the option for the whole order. The option is offered only when at least one item in the order has an
includescategory, and withheld when any item has anexcludescategory. To scope the option per item instead, useitem_product_categories. - Item-level category condition: scopes the option per item instead of showing or hiding it for the whole order. With
includes, the option applies only to items whose category is listed; withexcludes, items with a listed category are excluded and every other item qualifies. Non-matching items are marked unavailable for the option in storefront delivery-options responses (availability: NONE,fulfillable_quantity: 0), and an option no cart item matches is not returned. An item with no category fails a non-emptyincludeslist and passes an excludes-only condition. Matching is case-insensitive and ignores surrounding whitespace. - For
COLLECTIONmethods: IDs of the Carriyo locations the customer can collect from. Only locations with thecollection_locationflag enabled are accepted. An empty or omitted list means any location: at storefront read time the option resolves to everyACTIVEcollection-enabled location the merchant can use, restricted to the customer's country. An explicit list is honored as-is — it is not filtered by the customer's country, so a merchant can deliberately include cross-border collection points (unlike the any-location behaviour, which is always same-country). - For
COLLECTIONmethods: maximum distance from the customer to a candidate collection location. Enforced only when the storefront request supplies the customer's coordinates — it is a proximity bound, not a country bound, so a radius near a border can legitimately include cross-border locations from an explicit list.
error-responseerror-responseNeed the full machine-readable spec? Download the OpenAPI document →
/delivery-options/{delivery-option-id}Delete delivery option
Permanently deletes the delivery option with this id. This cannot be undone.
Behavior
Answers 204 with no body.
Errors
404— no delivery option has thisid.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| delivery-option-id | string | Yes | The `id` returned by create or list. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
error-responseNeed the full machine-readable spec? Download the OpenAPI document →
Webhooks
A webhook is a configuration under which Carriyo pushes events for one entity_type to your endpoint as JSON over HTTPS: the target url, custom headers, the merchants it applies to, and its triggers. A trigger is a notify_status value or a notify_* flag, and every event delivered names its trigger in the trigger header. Any response outside the 2xx range is a failed delivery; Carriyo retries automatically, and events that still fail can be read and retriggered through the failed-events operations. Carriyo assigns config_id; a configuration can be replaced, and deleting one is permanent. Reading an unknown config_id answers 200 with an empty body; updating or deleting one answers 400.
7 operations · 0 objects
/webhooksCreate webhook
Creates a webhook configuration that delivers events for one entity_type to your endpoint, and assigns its config_id.
Behavior
What to send
config_name,urlandentity_typeare required.config_namemust be unique among configurations that share a merchant.merchantsis required for everyentity_typeexceptINVENTORY, where whatever you send is replaced by["_ANY"]; each merchant named must exist.urlis stored as sent and not checked for format, so a malformed URL is accepted and only fails at delivery.headersholds any custom headers sent with each delivery, such as the credentials your endpoint expects.
Triggers
A configuration must have at least one trigger. What counts depends on entity_type:
INVENTORY—notify_statusmust be exactly["ALL_INVENTORY_UPDATES"].SHIPMENT(and the deprecatedREVERSE_SHIPMENT) — a non-emptynotify_status, or one ofnotify_label_update,notify_carriyo_label_update,notify_commercial_invoice_update,notify_promised_delivery_date,notify_scheduled_collection,notify_scheduled_delivery.RETURN_REQUEST— a non-emptynotify_status, ornotify_rma_received_itemsornotify_rma_returned_items.ORDER,ORDER_CHANGE_REQUEST,ORDER_DELIVERY_CLAIM,COLLECTION— a non-emptynotify_status.
Status and limits
status defaults to ACTIVE. An INACTIVE configuration receives nothing and does not count toward the ACTIVE limit.
Two limits apply. The total number of configurations may not exceed your plan's webhook limit plus a buffer of 10; a request beyond it is rejected. A request that would exceed the plan's ACTIVE limit is stored INACTIVE rather than rejected, so check status in the response.
Delivery and retries
Carriyo waits up to 30 seconds to connect and 30 seconds for the response, treats any response outside the 2xx range as a failed delivery, retries three times, and retries five more times when extended_webhook_retries_enabled is set on the configuration.
Errors
400—config_name,urlorentity_typeis missing.400— no trigger is set for the chosenentity_type.400—merchantsis missing for anentity_typeother thanINVENTORY.400—merchantsnames a merchant that does not exist.400—config_nameis already used by a configuration that shares a merchant.400— the tenant has reached its total webhook limit.
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
Request body
application/jsonSchema: webhook-request- Status events to deliver, by
entity_type.SHIPMENTandREVERSE_SHIPMENTtake shipment status values and need at least one entry unless a shipmentnotify_*trigger is true;RETURN_REQUESTtakes return request status values and needs at least one entry unlessnotify_rma_received_itemsornotify_rma_returned_itemsis true;ORDER,ORDER_CHANGE_REQUEST,ORDER_DELIVERY_CLAIMandCOLLECTIONneed at least one non-blank entry;INVENTORYmust be exactly["ALL_INVENTORY_UPDATES"].
Responses
webhook-response- Status events to deliver, by
entity_type.SHIPMENTandREVERSE_SHIPMENTtake shipment status values and need at least one entry unless a shipmentnotify_*trigger is true;RETURN_REQUESTtakes return request status values and needs at least one entry unlessnotify_rma_received_itemsornotify_rma_returned_itemsis true;ORDER,ORDER_CHANGE_REQUEST,ORDER_DELIVERY_CLAIMandCOLLECTIONneed at least one non-blank entry;INVENTORYmust be exactly["ALL_INVENTORY_UPDATES"].
error-responseNeed the full machine-readable spec? Download the OpenAPI document →
/webhooksList webhooks
Returns all of the tenant's webhook configurations in a single unpaged array.
Behavior
There are no query parameters. The array holds configurations of every status, INACTIVE included, and is limited to the merchants the API key can access.
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
An array of webhook-response. Each item has the following fields:
- Status events to deliver, by
entity_type.SHIPMENTandREVERSE_SHIPMENTtake shipment status values and need at least one entry unless a shipmentnotify_*trigger is true;RETURN_REQUESTtakes return request status values and needs at least one entry unlessnotify_rma_received_itemsornotify_rma_returned_itemsis true;ORDER,ORDER_CHANGE_REQUEST,ORDER_DELIVERY_CLAIMandCOLLECTIONneed at least one non-blank entry;INVENTORYmust be exactly["ALL_INVENTORY_UPDATES"].
Need the full machine-readable spec? Download the OpenAPI document →
/webhooks/failed-eventsRetrieve failed webhook events
Returns the events of one webhook configuration that failed delivery within a time window.
Behavior
What to send. webhook_id, start_date and end_date are all required. The window may span at most 1 day; give both dates in UTC as yyyy-MM-dd'T'HH:mm:ss.SSSXXX (for example 2023-03-22T10:15:30.123Z). Failed events expire after 30 days, so an older window returns nothing.
What counts as failed. A failed webhook event is one where Carriyo received a response outside the 2xx range from your endpoint. Events remain here after the automatic retries are exhausted.
Response. original_failure_count is the number of events that failed in the window and current_failure_count the number still failed; failed_events lists those. The response is not paged. When no event failed in the window the call still answers 200, with error_message set instead of the counts; check it before reading them.
Errors
200witherror_message— no events failed in the window.400—webhook_id,start_dateorend_dateis missing.500— the window is longer than 1 day.500— a date is malformed.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
| webhook_id | string | Yes | The `config_id` of the webhook configuration. |
| start_date | string | Yes | Start of the window, UTC, as `yyyy-MM-dd'T'HH:mm:ss.SSSXXX` (a literal `Z` or `+00:00` offset; `+0000` is rejected). |
| end_date | string | Yes | End of the window, same format. At most 1 day after `start_date`. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
webhook-failed-events-success-responsewebhook-failed-events-error-responseNeed the full machine-readable spec? Download the OpenAPI document →
/webhooks/retrigger-failed-eventsRetrigger failed webhook events
Queues failed events of one webhook configuration for delivery again.
Behavior
What to send. webhook_id is required in both modes, plus one of two selections:
- by entity:
entity_idsandtriggername the events to resend, wheretriggeris the value delivered in the failed event'striggerheader; this mode wins wheneverentity_idsis non-empty. - by window:
start_dateandend_datebound a window of at most 1 day, in UTC asyyyy-MM-dd'T'HH:mm:ss.SSSXXX; failed events expire after 30 days, so an older window returns nothing.
What counts as failed. A failed webhook event is one where Carriyo received a response outside the 2xx range from your endpoint.
What happens. Delivery is asynchronous: 200 means the events were queued, not that they were delivered. An event whose last attempt succeeded, or whose payload is no longer available, is skipped and does not appear in retriggered_events. In window mode, a window holding more than 1,000 failed events is not retriggered at all; narrow the window and call again.
Response. original_failure_count is the number of events that failed for the selection and retriggered_count the number queued; retriggered_events lists those. A body with neither selection answers 200 with an empty object.
Errors
200witherror_message— more than 1,000 events failed in the window.200with an empty object — neitherentity_idsnor both dates were sent.400—start_dateandend_dateare present butwebhook_idis empty.500—entity_idsis given buttriggerorwebhook_idis missing.500— the window is longer than 1 day.500— a date is malformed.
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
Request body
application/jsonSchema: webhook-retrigger-failed-events-requestrequiredResponses
webhook-retrigger-failed-events-success-responsewebhook-retrigger-failed-events-error-responseNeed the full machine-readable spec? Download the OpenAPI document →
/webhooks/{webhook-id}Get webhook
Returns the webhook configuration with this config_id.
Behavior
An unknown config_id is not an error: the call answers 200 with an empty body, so check for a body before parsing.
Errors
200with an empty body — no webhook configuration has thisconfig_id.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| webhook-id | string | Yes | The `config_id` returned by create or list. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
webhook-response- Status events to deliver, by
entity_type.SHIPMENTandREVERSE_SHIPMENTtake shipment status values and need at least one entry unless a shipmentnotify_*trigger is true;RETURN_REQUESTtakes return request status values and needs at least one entry unlessnotify_rma_received_itemsornotify_rma_returned_itemsis true;ORDER,ORDER_CHANGE_REQUEST,ORDER_DELIVERY_CLAIMandCOLLECTIONneed at least one non-blank entry;INVENTORYmust be exactly["ALL_INVENTORY_UPDATES"].
Need the full machine-readable spec? Download the OpenAPI document →
/webhooks/{webhook-id}Update webhook
Replaces the webhook configuration with this config_id with the request body.
Behavior
What happens
Every field is set to the value supplied; a field omitted from the request is cleared. Only config_id and creation_date are kept from the stored configuration. The ACTIVE limit is not applied on update: a request that moves status to ACTIVE at the limit is stored ACTIVE regardless.
What to send
config_name,urlandentity_typeare required;config_nameis not checked for uniqueness on update.merchantsis required for everyentity_typeexceptINVENTORY, where whatever you send is replaced by["_ANY"]; each merchant named must exist.urlis stored as sent and not checked for format, so a malformed URL is accepted and only fails at delivery.
Triggers
A configuration must have at least one trigger. What counts depends on entity_type:
INVENTORY—notify_statusmust be exactly["ALL_INVENTORY_UPDATES"].SHIPMENT(and the deprecatedREVERSE_SHIPMENT) — a non-emptynotify_status, or one ofnotify_label_update,notify_carriyo_label_update,notify_commercial_invoice_update,notify_promised_delivery_date,notify_scheduled_collection,notify_scheduled_delivery.RETURN_REQUEST— a non-emptynotify_status, ornotify_rma_received_itemsornotify_rma_returned_items.ORDER,ORDER_CHANGE_REQUEST,ORDER_DELIVERY_CLAIM,COLLECTION— a non-emptynotify_status.
Response
Unlike create, get and list, this call returns the stored configuration with mostly camelCase keys (configId, configName, notifyStatus, entityType, updateDate), while creation_date, updated_by_user, authentication and extended_webhook_retries_enabled stay snake_case; this is a known defect. Do not parse it with the same model as the other webhook responses.
Delivery and retries
Carriyo waits up to 30 seconds to connect and 30 seconds for the response, treats any response outside the 2xx range as a failed delivery, retries three times, and retries five more times when extended_webhook_retries_enabled is set on the configuration.
Errors
400—config_name,urlorentity_typeis missing.400— no trigger is set for the chosenentity_type.400—merchantsis missing for anentity_typeother thanINVENTORY.400—merchantsnames a merchant that does not exist.400— no webhook configuration has thisconfig_id.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| webhook-id | string | Yes | The `config_id` returned by create or list. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
Request body
application/jsonSchema: webhook-request- Status events to deliver, by
entity_type.SHIPMENTandREVERSE_SHIPMENTtake shipment status values and need at least one entry unless a shipmentnotify_*trigger is true;RETURN_REQUESTtakes return request status values and needs at least one entry unlessnotify_rma_received_itemsornotify_rma_returned_itemsis true;ORDER,ORDER_CHANGE_REQUEST,ORDER_DELIVERY_CLAIMandCOLLECTIONneed at least one non-blank entry;INVENTORYmust be exactly["ALL_INVENTORY_UPDATES"].
Responses
webhook-update-responseerror-responseNeed the full machine-readable spec? Download the OpenAPI document →
/webhooks/{webhook-id}Delete webhook
Permanently deletes the webhook configuration with this config_id. This cannot be undone.
Behavior
Retries already scheduled for the configuration are not cancelled; when they fire they find no active configuration and deliver nothing.
Errors
400— no webhook configuration has thisconfig_id.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| webhook-id | string | Yes | The `config_id` returned by create or list. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
error-responseNeed the full machine-readable spec? Download the OpenAPI document →
Attributes
A custom attribute extends the Carriyo data model with a field of your own: defined once with a name, a type and the scopes it can be set on, then referenced by name on orders, shipments, returns, products, addresses or locations. Creating and deleting custom attributes requires a subscription that includes them, attribute_name is fixed once created, and deleting one is permanent. An unknown custom_attribute_id answers 404 on read, update and delete.
5 operations · 0 objects
/attributesCreate custom attribute
Creates a custom attribute and assigns its custom_attribute_id.
Behavior
What to send. attribute_name, attribute_type and attribute_scopes are required; attribute_name must be unique and cannot be changed after creation. allowed_values is required when attribute_type is ENUM and is discarded for every other type.
Precondition. Creating a custom attribute requires a subscription that includes custom attributes.
Errors
400— the tenant's subscription does not include custom attributes.400—attribute_namealready exists.400— anADDRESS-scopedattribute_nameclashes with a built-in address field.400—attribute_typeisENUMandallowed_valuesis missing.400—allowed_valuescontains a blank value.400—allowed_valuescontains a duplicate value.
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
Request body
application/jsonSchema: attribute-requestResponses
attribute-responseerror-responseNeed the full machine-readable spec? Download the OpenAPI document →
/attributesList custom attributes
Returns all of the tenant's custom attributes in a single unpaged array.
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
An array of attribute-response. Each item has the following fields:
Need the full machine-readable spec? Download the OpenAPI document →
/attributes/{attribute-id}Get custom attribute
Returns the custom attribute with this custom_attribute_id.
Errors
404— no custom attribute has thiscustom_attribute_id.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| attribute-id | string | Yes | The `custom_attribute_id` returned by create or list. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
attribute-responseerror-responseNeed the full machine-readable spec? Download the OpenAPI document →
/attributes/{attribute-id}Update custom attribute
Updates the custom attribute with this custom_attribute_id.
Behavior
What changes. attribute_name is fixed at creation; attribute_type, attribute_scopes and allowed_values can be changed. allowed_values replaces the stored list, and removing a value that an automation, service-level, shipment-costing or capacity rule still references is refused.
Precondition. Unlike create and delete, update does not require the subscription to include custom attributes.
Errors
400—allowed_valuesno longer contains a value that a rule references.400—attribute_typeisENUMandallowed_valuesis missing.400—allowed_valuescontains a blank value.400—allowed_valuescontains a duplicate value.404— no custom attribute has thiscustom_attribute_id.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| attribute-id | string | Yes | The `custom_attribute_id` returned by create or list. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
Request body
application/jsonSchema: attribute-update-requestResponses
attribute-responseerror-responseerror-responseNeed the full machine-readable spec? Download the OpenAPI document →
/attributes/{attribute-id}Delete custom attribute
Permanently deletes the custom attribute with this custom_attribute_id. This cannot be undone.
Behavior
Values already stored on every entity in its scopes are preserved, but the attribute can no longer be set on new ones. Rules are not changed: the delete is refused while an automation, service-level, shipment-costing or capacity rule references the attribute. Deleting requires a subscription that includes custom attributes.
Errors
400— an automation, service-level, shipment-costing or capacity rule still references the attribute.400— the tenant's subscription does not include custom attributes.404— no custom attribute has thiscustom_attribute_id.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| attribute-id | string | Yes | The `custom_attribute_id` returned by create or list. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
error-responseerror-responseNeed the full machine-readable spec? Download the OpenAPI document →