API reference

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 shipment attributes.

Use the Carriyo Dashboard for setup

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.

Serverhttps://api.carriyo.comAuthOAuth 2.0 + API KeySpeccore.yaml

Delivery Types

A delivery type represents the type of delivery service chosen by the customer. Delivery types are defined by the merchant and typically have values such as "Same Day", "Next Day", or "International".

4 operations · 0 objects

post/delivery-types

Create delivery type

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Creates a new delivery type.

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

Content type: application/jsonSchema: delivery-type-request

codestringrequired
Unique code identifying the delivery type. Maximum 250 characters.
merchantsstring[]

Responses

201Delivery type created.Schema: delivery-type-response

delivery_type_idstringrequired
codestringrequired
merchantsstring[]
deletedboolean

400Validation failed. For example: `code` exceeds 250 characters; `code` is required; or a delivery type with the same `code` already exists.Schema: error-response

errorsstring[]
Human-readable message(s) describing why the request failed.
statusstring
HTTP status reason (e.g. BAD_REQUEST, NOT_FOUND).
timestampstringformat: date-time

Need the full machine-readable spec? Download the OpenAPI document →

get/delivery-types

List delivery types

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Returns the merchant's delivery types.

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

200Matching delivery types.

delivery_type_idstringrequired
codestringrequired
merchantsstring[]
deletedboolean

Need the full machine-readable spec? Download the OpenAPI document →

get/delivery-types/{delivery-type-id}

Get delivery type

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Returns the specified delivery type. If the delivery type has been deleted, the deleted property is set to true on the response.

Path parameters

Name	Type	Required	Description
delivery-type-id	string	Yes	—

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

200Returns the requested delivery type.Schema: delivery-type-response

delivery_type_idstringrequired
codestringrequired
merchantsstring[]
deletedboolean

Need the full machine-readable spec? Download the OpenAPI document →

delete/delivery-types/{delivery-type-id}

Delete delivery type

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Permanently deletes the specified delivery type and removes references to it from rules and other settings. This cannot be undone.

Path parameters

Name	Type	Required	Description
delivery-type-id	string	Yes	—

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

200Delivery type deleted.Schema: delivery-type-response

delivery_type_idstringrequired
codestringrequired
merchantsstring[]
deletedboolean

Need the full machine-readable spec? Download the OpenAPI document →

Locations

A location is usually a store or warehouse used as a pickup or dropoff point for shipments or return requests. The merchant configures a location in Carriyo with a code, name, and address, and references it when creating shipments or returns.

7 operations · 0 objects

post/locations

Create location

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Creates a new location.

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

Content type: application/jsonSchema: location-request

location_codestring
location_namestringrequired
contact_namestringrequired
contact_emailstring
Conditionally mandatory based on Account Settings
contact_phonestring
Conditionally mandatory based on Account Settings
alternate_phonestring
address1stringrequired
address2string
citystringrequired
statestring
postcodestring
countrystringrequired
coordsstring
fulfillment_zoneslocation-fulfillment-zone[]
Geographies this location can fulfil (country, optionally narrowed to states / cities / areas). Mutually exclusive with fulfillment_radius — configure one or the other, not both. A location with neither serves everywhere.
fulfillment_radiusdistance
Radius around the location's coordinates within which it can fulfil. Mutually exclusive with fulfillment_zones (setting both is rejected). The value must be positive, and the location must have coords. Coverage is matched by distance, so an order or storefront request qualifies only when it carries customer coordinates.
address_codesaddress-code[]
typestring
Values:businessresidential
shopify_location_idstring
deletedboolean
merchantsstring[]

Responses

201Location created.Schema: location-response

location_idstringrequired
location_codestring
location_namestringrequired
contact_namestringrequired
contact_emailstring
contact_phonestring
alternate_phonestring
address1stringrequired
address2string
citystringrequired
statestring
postcodestring
countrystringrequired
coordsstring
fulfillment_zoneslocation-fulfillment-zone[]
Geographies this location can fulfil (country, optionally narrowed to states / cities / areas). Mutually exclusive with fulfillment_radius — configure one or the other, not both. A location with neither serves everywhere.
fulfillment_radiusdistance
Radius around the location's coordinates within which it can fulfil. Mutually exclusive with fulfillment_zones (setting both is rejected). The value must be positive, and the location must have coords. Coverage is matched by distance, so an order or storefront request qualifies only when it carries customer coordinates.
address_codesaddress-code[]
typestring
Values:businessresidential
shopify_location_idstring
deletedboolean
merchantsstring[]

Need the full machine-readable spec? Download the OpenAPI document →

get/locations

List locations

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Returns the merchant's locations.

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

200Matching locations.

location_idstringrequired
location_codestring
location_namestringrequired
contact_namestringrequired
contact_emailstring
contact_phonestring
alternate_phonestring
address1stringrequired
address2string
citystringrequired
statestring
postcodestring
countrystringrequired
coordsstring
fulfillment_zoneslocation-fulfillment-zone[]
Geographies this location can fulfil (country, optionally narrowed to states / cities / areas). Mutually exclusive with fulfillment_radius — configure one or the other, not both. A location with neither serves everywhere.
fulfillment_radiusdistance
Radius around the location's coordinates within which it can fulfil. Mutually exclusive with fulfillment_zones (setting both is rejected). The value must be positive, and the location must have coords. Coverage is matched by distance, so an order or storefront request qualifies only when it carries customer coordinates.
address_codesaddress-code[]
typestring
Values:businessresidential
shopify_location_idstring
deletedboolean
merchantsstring[]

Need the full machine-readable spec? Download the OpenAPI document →

get/locations/{location-id}

Get location

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Returns the specified location. If the location has been deleted, the deleted property is set to true on the response.

Path parameters

Name	Type	Required	Description
location-id	string	Yes	—

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

200Returns the requested location.Schema: location-response

location_idstringrequired
location_codestring
location_namestringrequired
contact_namestringrequired
contact_emailstring
contact_phonestring
alternate_phonestring
address1stringrequired
address2string
citystringrequired
statestring
postcodestring
countrystringrequired
coordsstring
fulfillment_zoneslocation-fulfillment-zone[]
Geographies this location can fulfil (country, optionally narrowed to states / cities / areas). Mutually exclusive with fulfillment_radius — configure one or the other, not both. A location with neither serves everywhere.
fulfillment_radiusdistance
Radius around the location's coordinates within which it can fulfil. Mutually exclusive with fulfillment_zones (setting both is rejected). The value must be positive, and the location must have coords. Coverage is matched by distance, so an order or storefront request qualifies only when it carries customer coordinates.
address_codesaddress-code[]
typestring
Values:businessresidential
shopify_location_idstring
deletedboolean
merchantsstring[]

Need the full machine-readable spec? Download the OpenAPI document →

put/locations/{location-id}

Update location

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Updates the specified location. All fields are updated to the values supplied in the request body; fields omitted from the request are cleared.

Path parameters

Name	Type	Required	Description
location-id	string	Yes	—

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

Content type: application/jsonSchema: location-request

location_codestring
location_namestringrequired
contact_namestringrequired
contact_emailstring
Conditionally mandatory based on Account Settings
contact_phonestring
Conditionally mandatory based on Account Settings
alternate_phonestring
address1stringrequired
address2string
citystringrequired
statestring
postcodestring
countrystringrequired
coordsstring
fulfillment_zoneslocation-fulfillment-zone[]
Geographies this location can fulfil (country, optionally narrowed to states / cities / areas). Mutually exclusive with fulfillment_radius — configure one or the other, not both. A location with neither serves everywhere.
fulfillment_radiusdistance
Radius around the location's coordinates within which it can fulfil. Mutually exclusive with fulfillment_zones (setting both is rejected). The value must be positive, and the location must have coords. Coverage is matched by distance, so an order or storefront request qualifies only when it carries customer coordinates.
address_codesaddress-code[]
typestring
Values:businessresidential
shopify_location_idstring
deletedboolean
merchantsstring[]

Responses

200Location updated.Schema: location-response

location_idstringrequired
location_codestring
location_namestringrequired
contact_namestringrequired
contact_emailstring
contact_phonestring
alternate_phonestring
address1stringrequired
address2string
citystringrequired
statestring
postcodestring
countrystringrequired
coordsstring
fulfillment_zoneslocation-fulfillment-zone[]
Geographies this location can fulfil (country, optionally narrowed to states / cities / areas). Mutually exclusive with fulfillment_radius — configure one or the other, not both. A location with neither serves everywhere.
fulfillment_radiusdistance
Radius around the location's coordinates within which it can fulfil. Mutually exclusive with fulfillment_zones (setting both is rejected). The value must be positive, and the location must have coords. Coverage is matched by distance, so an order or storefront request qualifies only when it carries customer coordinates.
address_codesaddress-code[]
typestring
Values:businessresidential
shopify_location_idstring
deletedboolean
merchantsstring[]

Need the full machine-readable spec? Download the OpenAPI document →

patch/locations/{location-id}

Partially update location

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Partially updates the specified location. Only the fields included in the request body are changed; fields omitted are left unchanged. (The full PUT update, by contrast, clears omitted fields.)

Path parameters

Name	Type	Required	Description
location-id	string	Yes	—

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

Content type: application/jsonSchema: patch-location-request

location_codestring
location_namestring
contact_namestring
contact_emailstring
Conditionally mandatory based on Account Settings
contact_phonestring
Conditionally mandatory based on Account Settings
alternate_phonestring
address1string
address2string
citystring
statestring
postcodestring
countrystring
coordsstring
fulfillment_zoneslocation-fulfillment-zone[]
Geographies this location can fulfil (country, optionally narrowed to states, cities, or areas). Supplying fulfillment_zones on a PATCH clears any existing fulfillment_radius, so you can switch a location from radius to zone coverage in a single call. Supplying both fulfillment_zones and fulfillment_radius in the same request is rejected. A location with neither serves everywhere.
fulfillment_radiusdistance
Radius around the location's coordinates within which it can fulfil. Supplying fulfillment_radius on a PATCH clears any existing fulfillment_zones, so you can switch a location from zone to radius coverage in a single call. Supplying both in the same request is rejected. The value must be positive, and the location must have coords. Coverage is matched by distance, so an order or storefront request qualifies only when it carries customer coordinates.
address_codesaddress-code[]
typestring
Values:businessresidential
shopify_location_idstring
deletedboolean
merchantsstring[]

Responses

200Location updated.Schema: location-response

location_idstringrequired
location_codestring
location_namestringrequired
contact_namestringrequired
contact_emailstring
contact_phonestring
alternate_phonestring
address1stringrequired
address2string
citystringrequired
statestring
postcodestring
countrystringrequired
coordsstring
fulfillment_zoneslocation-fulfillment-zone[]
Geographies this location can fulfil (country, optionally narrowed to states / cities / areas). Mutually exclusive with fulfillment_radius — configure one or the other, not both. A location with neither serves everywhere.
fulfillment_radiusdistance
Radius around the location's coordinates within which it can fulfil. Mutually exclusive with fulfillment_zones (setting both is rejected). The value must be positive, and the location must have coords. Coverage is matched by distance, so an order or storefront request qualifies only when it carries customer coordinates.
address_codesaddress-code[]
typestring
Values:businessresidential
shopify_location_idstring
deletedboolean
merchantsstring[]

Need the full machine-readable spec? Download the OpenAPI document →

delete/locations/{location-id}

Delete location

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Permanently deletes the specified location and removes references to it from rules and other settings. This cannot be undone.

Path parameters

Name	Type	Required	Description
location-id	string	Yes	—

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

200Location deleted.Schema: location-response

location_idstringrequired
location_codestring
location_namestringrequired
contact_namestringrequired
contact_emailstring
contact_phonestring
alternate_phonestring
address1stringrequired
address2string
citystringrequired
statestring
postcodestring
countrystringrequired
coordsstring
fulfillment_zoneslocation-fulfillment-zone[]
Geographies this location can fulfil (country, optionally narrowed to states / cities / areas). Mutually exclusive with fulfillment_radius — configure one or the other, not both. A location with neither serves everywhere.
fulfillment_radiusdistance
Radius around the location's coordinates within which it can fulfil. Mutually exclusive with fulfillment_zones (setting both is rejected). The value must be positive, and the location must have coords. Coverage is matched by distance, so an order or storefront request qualifies only when it carries customer coordinates.
address_codesaddress-code[]
typestring
Values:businessresidential
shopify_location_idstring
deletedboolean
merchantsstring[]

Need the full machine-readable spec? Download the OpenAPI document →

post/locations/bulk/import

Bulk import locations

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Create or update multiple locations in one request. Each entry is matched by location_code: if a location with that code already exists it is updated; otherwise a new location is created.

Processing

Rows are processed in parallel.
Duplicate location_code or location_name values within the same request are rejected.
Quota limits may reject additional rows when the tenant is at its location cap.

Limits

Batch size is capped by the tenant bulk.import.limit setting (commonly 20 locations per request). Split larger imports into multiple calls.

Response

Returns one entry per input row. Each entry includes:

result: accepted when the row was created or updated; rejected otherwise.
reason: detail when result is rejected.
location: the saved location when result is accepted.
locationCode: the code from the request (useful when location is absent).

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

Content type: application/jsonSchema: location-bulk-import-requestrequired

location_requestslocation-request[]required
Locations to import. Each item follows the same shape as POST /locations.

Responses

200Per-location import outcomes, in the same order as `location_requests`.

resultstring
Whether the row was applied (accepted) or skipped (rejected).
Values:acceptedrejected
locationlocation-response
reasonstring
Human-readable detail when result is rejected.
locationCodestring
The location_code from the request for correlation when import failed.

400Invalid request (for example, empty `location_requests` or batch over the tenant limit).Schema: error-response

errorsstring[]
Human-readable message(s) describing why the request failed.
statusstring
HTTP status reason (e.g. BAD_REQUEST, NOT_FOUND).
timestampstringformat: date-time

Need the full machine-readable spec? Download the OpenAPI document →

Order Types

An order type represents the order journey chosen by the customer. Order types are defined by the merchant and typically have values such as "Home Delivery" or "Click & Collect".

4 operations · 0 objects

post/order-types

Create order type

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Creates a new order type.

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

Content type: application/jsonSchema: order-type-request

codestringrequired
Unique code identifying the order type. Maximum 250 characters.
merchantsstring[]

Responses

201Order type created.Schema: order-type-response

idstringrequired
codestringrequired
merchantsstring[]
deletedboolean

400Validation failed. For example: `code` exceeds 250 characters; `code` is required; or an order type with the same `code` already exists.Schema: error-response

errorsstring[]
Human-readable message(s) describing why the request failed.
statusstring
HTTP status reason (e.g. BAD_REQUEST, NOT_FOUND).
timestampstringformat: date-time

Need the full machine-readable spec? Download the OpenAPI document →

get/order-types

List order types

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Returns the merchant's order types, most recently created first.

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

200Matching order types.

idstringrequired
codestringrequired
merchantsstring[]
deletedboolean

Need the full machine-readable spec? Download the OpenAPI document →

get/order-types/{order-type-id}

Get order type

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Returns the specified order type. If the order type has been deleted, the deleted property is set to true on the response.

Path parameters

Name	Type	Required	Description
order-type-id	string	Yes	—

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

200Returns the requested order type.Schema: order-type-response

idstringrequired
codestringrequired
merchantsstring[]
deletedboolean

Need the full machine-readable spec? Download the OpenAPI document →

delete/order-types/{order-type-id}

Delete order type

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Permanently deletes the specified order type and removes references to it from rules and other settings. This cannot be undone.

Path parameters

Name	Type	Required	Description
order-type-id	string	Yes	—

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

200Order type deleted.Schema: order-type-response

idstringrequired
codestringrequired
merchantsstring[]
deletedboolean

Need the full machine-readable spec? Download the OpenAPI document →

Time Slots

A time slot is used to schedule collections (pickup) and deliveries (dropoff). Each time slot has a code, name, and a start and end time. Time slots can be presented as pre-configured options to the customer when creating a shipment or a return.

4 operations · 0 objects

post/time-slots

Create time slot

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Creates a new time slot.

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

Content type: application/jsonSchema: time-slot

time_slot_idstringrequired
The ID to identify the time slot
fromstringrequired
The start time for the time slot
tostringrequired
The end time for the time slot. Must be later than from.

Responses

201Time slot created.Schema: time-slot

time_slot_idstringrequired
The ID to identify the time slot
fromstringrequired
The start time for the time slot
tostringrequired
The end time for the time slot. Must be later than from.

Need the full machine-readable spec? Download the OpenAPI document →

get/time-slots

List time slots

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Returns the merchant's time slots.

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

200Matching time slots.

time_slot_idstringrequired
The ID to identify the time slot
fromstringrequired
The start time for the time slot
tostringrequired
The end time for the time slot. Must be later than from.

Need the full machine-readable spec? Download the OpenAPI document →

get/time-slots/{time-slot-id}

Get time slot

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Returns the specified time slot.

Path parameters

Name	Type	Required	Description
time-slot-id	string	Yes	—

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

200Returns the requested time slot.Schema: time-slot

time_slot_idstringrequired
The ID to identify the time slot
fromstringrequired
The start time for the time slot
tostringrequired
The end time for the time slot. Must be later than from.

Need the full machine-readable spec? Download the OpenAPI document →

delete/time-slots/{time-slot-id}

Delete time slot

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Permanently deletes the specified time slot. This cannot be undone.

Path parameters

Name	Type	Required	Description
time-slot-id	string	Yes	—

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

200Time slot deleted.Schema: time-slot

time_slot_idstringrequired
The ID to identify the time slot
fromstringrequired
The start time for the time slot
tostringrequired
The end time for the time slot. Must be later than from.

Need 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. Each option carries the carrier account that fulfils it, its pricing and delivery-time estimate, and the eligibility conditions (geography, order value, weight, payment type) under which it appears. The merchant configures delivery options in the Carriyo Dashboard; the shopper-facing lookups that evaluate them live in the Storefront API.

5 operations · 0 objects

post/delivery-options

Create delivery option

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Creates a customer-facing delivery option (e.g. 'Same Day', 'Next Day Premium') with its associated carrier, schedule, fee, and eligibility conditions.

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

Content type: application/jsonSchema: delivery-optionrequired

idstring
Carriyo-issued identifier. Server-assigned on create.
codestring
Merchant-supplied code used as the option's stable identifier (e.g. EXPRESS_AE).
namestring
Human-readable display name shown to the customer.
descriptionstring
Optional longer description shown to the customer.
image_urlstring
URL of an icon / illustration for the option.
delivery_methodstring
Delivery method (home delivery, customer pickup, or digital fulfilment).
Values:DELIVERYCOLLECTIONDIGITAL
merchantstring
Merchant the option belongs to.
carrier_account_idstring
Carrier account that fulfils shipments booked via this option.
statusstring
Option status.
Values:ACTIVEINACTIVE
schedulecarrier-schedule
Working days / blackout dates for this option.
shipping_feeshipping-fee
Pricing configuration.
delivery_estimationdelivery-estimation
Customer-facing delivery-time estimation configuration.
order_valuenumber-area-condition
Make the option visible only when order value is in range.
weightnumber-area-condition
Make the option visible only when total weight is in range.
payment_typestring-condition
Make the option visible only for matching payment types.
customercountry-states-condition-v2
Make the option visible only when the customer address falls in matching country / states / cities / areas.
product_categoriesorder-category-condition
Make the option visible only for matching product categories in the order. Matching is case-insensitive.
fulfillment_locationsstring[]
Carriyo location codes/IDs eligible to fulfil this option.
customer_collection_locationsstring[]
For COLLECTION methods: location codes/IDs where the customer can collect from.
customer_collection_max_distancedistance
For COLLECTION methods: maximum distance from the customer to a candidate collection location.
updated_by_userstring
User identifier (email) of the last updater. Read-only.
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

Responses

201Delivery option created.Schema: delivery-option

idstring
Carriyo-issued identifier. Server-assigned on create.
codestring
Merchant-supplied code used as the option's stable identifier (e.g. EXPRESS_AE).
namestring
Human-readable display name shown to the customer.
descriptionstring
Optional longer description shown to the customer.
image_urlstring
URL of an icon / illustration for the option.
delivery_methodstring
Delivery method (home delivery, customer pickup, or digital fulfilment).
Values:DELIVERYCOLLECTIONDIGITAL
merchantstring
Merchant the option belongs to.
carrier_account_idstring
Carrier account that fulfils shipments booked via this option.
statusstring
Option status.
Values:ACTIVEINACTIVE
schedulecarrier-schedule
Working days / blackout dates for this option.
shipping_feeshipping-fee
Pricing configuration.
delivery_estimationdelivery-estimation
Customer-facing delivery-time estimation configuration.
order_valuenumber-area-condition
Make the option visible only when order value is in range.
weightnumber-area-condition
Make the option visible only when total weight is in range.
payment_typestring-condition
Make the option visible only for matching payment types.
customercountry-states-condition-v2
Make the option visible only when the customer address falls in matching country / states / cities / areas.
product_categoriesorder-category-condition
Make the option visible only for matching product categories in the order. Matching is case-insensitive.
fulfillment_locationsstring[]
Carriyo location codes/IDs eligible to fulfil this option.
customer_collection_locationsstring[]
For COLLECTION methods: location codes/IDs where the customer can collect from.
customer_collection_max_distancedistance
For COLLECTION methods: maximum distance from the customer to a candidate collection location.
updated_by_userstring
User identifier (email) of the last updater. Read-only.
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

Need the full machine-readable spec? Download the OpenAPI document →

get/delivery-options

List delivery options

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Returns the merchant's delivery options.

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

200The merchant's delivery options.

idstring
Carriyo-issued identifier. Server-assigned on create.
codestring
Merchant-supplied code used as the option's stable identifier (e.g. EXPRESS_AE).
namestring
Human-readable display name shown to the customer.
descriptionstring
Optional longer description shown to the customer.
image_urlstring
URL of an icon / illustration for the option.
delivery_methodstring
Delivery method (home delivery, customer pickup, or digital fulfilment).
Values:DELIVERYCOLLECTIONDIGITAL
merchantstring
Merchant the option belongs to.
carrier_account_idstring
Carrier account that fulfils shipments booked via this option.
statusstring
Option status.
Values:ACTIVEINACTIVE
schedulecarrier-schedule
Working days / blackout dates for this option.
shipping_feeshipping-fee
Pricing configuration.
delivery_estimationdelivery-estimation
Customer-facing delivery-time estimation configuration.
order_valuenumber-area-condition
Make the option visible only when order value is in range.
weightnumber-area-condition
Make the option visible only when total weight is in range.
payment_typestring-condition
Make the option visible only for matching payment types.
customercountry-states-condition-v2
Make the option visible only when the customer address falls in matching country / states / cities / areas.
product_categoriesorder-category-condition
Make the option visible only for matching product categories in the order. Matching is case-insensitive.
fulfillment_locationsstring[]
Carriyo location codes/IDs eligible to fulfil this option.
customer_collection_locationsstring[]
For COLLECTION methods: location codes/IDs where the customer can collect from.
customer_collection_max_distancedistance
For COLLECTION methods: maximum distance from the customer to a candidate collection location.
updated_by_userstring
User identifier (email) of the last updater. Read-only.
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

Need the full machine-readable spec? Download the OpenAPI document →

get/delivery-options/{delivery-option-id}

Get delivery option

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Returns the specified delivery option.

Path parameters

Name	Type	Required	Description
delivery-option-id	string	Yes	Delivery option ID.

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

200Returns the requested delivery option.Schema: delivery-option

idstring
Carriyo-issued identifier. Server-assigned on create.
codestring
Merchant-supplied code used as the option's stable identifier (e.g. EXPRESS_AE).
namestring
Human-readable display name shown to the customer.
descriptionstring
Optional longer description shown to the customer.
image_urlstring
URL of an icon / illustration for the option.
delivery_methodstring
Delivery method (home delivery, customer pickup, or digital fulfilment).
Values:DELIVERYCOLLECTIONDIGITAL
merchantstring
Merchant the option belongs to.
carrier_account_idstring
Carrier account that fulfils shipments booked via this option.
statusstring
Option status.
Values:ACTIVEINACTIVE
schedulecarrier-schedule
Working days / blackout dates for this option.
shipping_feeshipping-fee
Pricing configuration.
delivery_estimationdelivery-estimation
Customer-facing delivery-time estimation configuration.
order_valuenumber-area-condition
Make the option visible only when order value is in range.
weightnumber-area-condition
Make the option visible only when total weight is in range.
payment_typestring-condition
Make the option visible only for matching payment types.
customercountry-states-condition-v2
Make the option visible only when the customer address falls in matching country / states / cities / areas.
product_categoriesorder-category-condition
Make the option visible only for matching product categories in the order. Matching is case-insensitive.
fulfillment_locationsstring[]
Carriyo location codes/IDs eligible to fulfil this option.
customer_collection_locationsstring[]
For COLLECTION methods: location codes/IDs where the customer can collect from.
customer_collection_max_distancedistance
For COLLECTION methods: maximum distance from the customer to a candidate collection location.
updated_by_userstring
User identifier (email) of the last updater. Read-only.
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

Need the full machine-readable spec? Download the OpenAPI document →

put/delivery-options/{delivery-option-id}

Update delivery option

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Updates the specified delivery option.

Path parameters

Name	Type	Required	Description
delivery-option-id	string	Yes	Delivery option ID.

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

Content type: application/jsonSchema: delivery-optionrequired

idstring
Carriyo-issued identifier. Server-assigned on create.
codestring
Merchant-supplied code used as the option's stable identifier (e.g. EXPRESS_AE).
namestring
Human-readable display name shown to the customer.
descriptionstring
Optional longer description shown to the customer.
image_urlstring
URL of an icon / illustration for the option.
delivery_methodstring
Delivery method (home delivery, customer pickup, or digital fulfilment).
Values:DELIVERYCOLLECTIONDIGITAL
merchantstring
Merchant the option belongs to.
carrier_account_idstring
Carrier account that fulfils shipments booked via this option.
statusstring
Option status.
Values:ACTIVEINACTIVE
schedulecarrier-schedule
Working days / blackout dates for this option.
shipping_feeshipping-fee
Pricing configuration.
delivery_estimationdelivery-estimation
Customer-facing delivery-time estimation configuration.
order_valuenumber-area-condition
Make the option visible only when order value is in range.
weightnumber-area-condition
Make the option visible only when total weight is in range.
payment_typestring-condition
Make the option visible only for matching payment types.
customercountry-states-condition-v2
Make the option visible only when the customer address falls in matching country / states / cities / areas.
product_categoriesorder-category-condition
Make the option visible only for matching product categories in the order. Matching is case-insensitive.
fulfillment_locationsstring[]
Carriyo location codes/IDs eligible to fulfil this option.
customer_collection_locationsstring[]
For COLLECTION methods: location codes/IDs where the customer can collect from.
customer_collection_max_distancedistance
For COLLECTION methods: maximum distance from the customer to a candidate collection location.
updated_by_userstring
User identifier (email) of the last updater. Read-only.
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

Responses

200Delivery option updated.Schema: delivery-option

idstring
Carriyo-issued identifier. Server-assigned on create.
codestring
Merchant-supplied code used as the option's stable identifier (e.g. EXPRESS_AE).
namestring
Human-readable display name shown to the customer.
descriptionstring
Optional longer description shown to the customer.
image_urlstring
URL of an icon / illustration for the option.
delivery_methodstring
Delivery method (home delivery, customer pickup, or digital fulfilment).
Values:DELIVERYCOLLECTIONDIGITAL
merchantstring
Merchant the option belongs to.
carrier_account_idstring
Carrier account that fulfils shipments booked via this option.
statusstring
Option status.
Values:ACTIVEINACTIVE
schedulecarrier-schedule
Working days / blackout dates for this option.
shipping_feeshipping-fee
Pricing configuration.
delivery_estimationdelivery-estimation
Customer-facing delivery-time estimation configuration.
order_valuenumber-area-condition
Make the option visible only when order value is in range.
weightnumber-area-condition
Make the option visible only when total weight is in range.
payment_typestring-condition
Make the option visible only for matching payment types.
customercountry-states-condition-v2
Make the option visible only when the customer address falls in matching country / states / cities / areas.
product_categoriesorder-category-condition
Make the option visible only for matching product categories in the order. Matching is case-insensitive.
fulfillment_locationsstring[]
Carriyo location codes/IDs eligible to fulfil this option.
customer_collection_locationsstring[]
For COLLECTION methods: location codes/IDs where the customer can collect from.
customer_collection_max_distancedistance
For COLLECTION methods: maximum distance from the customer to a candidate collection location.
updated_by_userstring
User identifier (email) of the last updater. Read-only.
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

Need the full machine-readable spec? Download the OpenAPI document →

delete/delivery-options/{delivery-option-id}

Delete delivery option

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Permanently deletes the specified delivery option. This cannot be undone.

Path parameters

Name	Type	Required	Description
delivery-option-id	string	Yes	Delivery option ID.

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

204Delivery option deleted.

Need the full machine-readable spec? Download the OpenAPI document →

Webhooks

A webhook lets Carriyo push real-time updates to your system. Carriyo sends notifications as JSON payloads over HTTPS, which your backend can use to trigger downstream actions. The webhook entity holds the configuration: triggers, target URL, custom headers, and so on.

7 operations · 0 objects

post/webhooks

Create webhook

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Create a webhook subscription. The configuration sets the target URL, the entity_type to listen on (Shipment, ReverseShipment, or ReturnRequest), the statuses to deliver via notify_status, and any custom headers used to authenticate the delivery to your endpoint.

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

Content type: application/jsonSchema: webhook-request

headersobject
merchantsstring[]
pickupobject
dropoffobject
pickup_partner_location_idsstring
dropoff_partner_location_idsstring
custom_conditionsobject[]
config_namestringrequired
urlstringrequired
statusstring
Values:ACTIVEINACTIVE
entity_typestring
Values:ShipmentReverseShipmentReturnRequest
notify_label_updateboolean
notify_carriyo_label_updateboolean
notify_rma_received_itemsboolean
notify_rma_returned_itemsboolean
notify_statusstring[]
initial_retry_frequencyinteger
max_retry_countinteger
internalboolean

Responses

201Webhook created.Schema: webhook-response

headersobject
merchantsstring[]
pickupobject
dropoffobject
pickup_partner_location_idsstring
dropoff_partner_location_idsstring
custom_conditionsobject[]
config_idstring
config_namestringrequired
urlstringrequired
statusstring
Values:ACTIVEINACTIVE
entity_typestring
Values:ShipmentReverseShipmentReturnRequest
notify_label_updateboolean
notify_carriyo_label_updateboolean
notify_rma_received_itemsboolean
notify_rma_returned_itemsboolean
notify_statusstring[]
initial_retry_frequencyinteger
max_retry_countinteger
internalboolean
update_datestring

Need the full machine-readable spec? Download the OpenAPI document →

get/webhooks

List webhooks

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Returns the merchant's webhooks.

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

200Matching webhooks.

headersobject
merchantsstring[]
pickupobject
dropoffobject
pickup_partner_location_idsstring
dropoff_partner_location_idsstring
custom_conditionsobject[]
config_idstring
config_namestringrequired
urlstringrequired
statusstring
Values:ACTIVEINACTIVE
entity_typestring
Values:ShipmentReverseShipmentReturnRequest
notify_label_updateboolean
notify_carriyo_label_updateboolean
notify_rma_received_itemsboolean
notify_rma_returned_itemsboolean
notify_statusstring[]
initial_retry_frequencyinteger
max_retry_countinteger
internalboolean
update_datestring

Need the full machine-readable spec? Download the OpenAPI document →

get/webhooks/failed-events

Retrieve failed webhook events

Retrieve webhook events that failed within a given time range. The range can span up to 1 day and can reach back as far as the last 30 days.

A failed webhook event is one where Carriyo received a non-200 response from your endpoint.

Set start_date and end_date in ISO 8601 format (for example 2023-03-22T10:15:30.123Z) to define the range.

Query parameters

Name	Type	Required	Description
webhook_id	string	Yes	ID of the Carriyo webhook configuration
start_date	string	Yes	The start date and time in ISO 8601 format with milliseconds. Pattern: yyyy-MM-dd'T'HH:mm:ss.SSSZ
end_date	string	Yes	The end date and time in ISO 8601 format with milliseconds. Pattern: yyyy-MM-dd'T'HH:mm:ss.SSSZ

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

200Success ResponseSchema: webhook-failed-events-success-response

original_failure_countintegerrequired
Total number of events that originally failed within the specified time window or for the specified entities (e.g., shipments or return requests).
current_failure_countintegerrequired
Total number of failed events that are still in the failed state.
failed_eventsobject[]required

400Error ResponseSchema: webhook-failed-events-error-response

error_messagestringrequired

Need the full machine-readable spec? Download the OpenAPI document →

post/webhooks/retrigger-failed-events

Retrigger failed webhook events

Manually retrigger failed webhook events, for when your endpoint was unavailable or kept failing beyond the automatic retry limit.

A failed webhook event is one where Carriyo received a non-200 response from your endpoint.

Specify a time range of up to 1 day, reaching back as far as the last 30 days. Each call retriggers at most 1,000 events.

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

Content type: application/jsonSchema: webhook-retrigger-failed-events-requestrequired

webhook_idstringrequired
ID of the Carriyo webhook configuration
start_datestringrequiredformat: date-time
The start date and time in ISO 8601 format with milliseconds. Pattern: yyyy-MM-dd'T'HH:mm:ss.SSSZ
end_datestringrequiredformat: date-time
The end date and time in ISO 8601 format with milliseconds. Pattern: yyyy-MM-dd'T'HH:mm:ss.SSSZ

Responses

200Success ResponseSchema: webhook-retrigger-failed-events-success-response

original_failure_countintegerrequired
Total number of events that originally failed within the specified time window or for the specified entities (e.g., shipments or return requests).
retriggered_countintegerrequired
Total number of failed events that were retriggered to fulfill this request.
retriggered_eventsobject[]required

400Error ResponseSchema: webhook-retrigger-failed-events-error-response

error_messagestringrequired

Need the full machine-readable spec? Download the OpenAPI document →

get/webhooks/{webhook-id}

Get webhook

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Returns the specified webhook.

Path parameters

Name	Type	Required	Description
webhook-id	string	Yes	—

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

200Returns the requested webhook.Schema: webhook-response

headersobject
merchantsstring[]
pickupobject
dropoffobject
pickup_partner_location_idsstring
dropoff_partner_location_idsstring
custom_conditionsobject[]
config_idstring
config_namestringrequired
urlstringrequired
statusstring
Values:ACTIVEINACTIVE
entity_typestring
Values:ShipmentReverseShipmentReturnRequest
notify_label_updateboolean
notify_carriyo_label_updateboolean
notify_rma_received_itemsboolean
notify_rma_returned_itemsboolean
notify_statusstring[]
initial_retry_frequencyinteger
max_retry_countinteger
internalboolean
update_datestring

Need the full machine-readable spec? Download the OpenAPI document →

put/webhooks/{webhook-id}

Update webhook

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Updates the specified webhook. All fields are updated to the values supplied in the request body; fields omitted from the request are cleared.

Path parameters

Name	Type	Required	Description
webhook-id	string	Yes	—

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

Content type: application/jsonSchema: webhook-request

headersobject
merchantsstring[]
pickupobject
dropoffobject
pickup_partner_location_idsstring
dropoff_partner_location_idsstring
custom_conditionsobject[]
config_namestringrequired
urlstringrequired
statusstring
Values:ACTIVEINACTIVE
entity_typestring
Values:ShipmentReverseShipmentReturnRequest
notify_label_updateboolean
notify_carriyo_label_updateboolean
notify_rma_received_itemsboolean
notify_rma_returned_itemsboolean
notify_statusstring[]
initial_retry_frequencyinteger
max_retry_countinteger
internalboolean

Responses

200Webhook updated.Schema: webhook-response

headersobject
merchantsstring[]
pickupobject
dropoffobject
pickup_partner_location_idsstring
dropoff_partner_location_idsstring
custom_conditionsobject[]
config_idstring
config_namestringrequired
urlstringrequired
statusstring
Values:ACTIVEINACTIVE
entity_typestring
Values:ShipmentReverseShipmentReturnRequest
notify_label_updateboolean
notify_carriyo_label_updateboolean
notify_rma_received_itemsboolean
notify_rma_returned_itemsboolean
notify_statusstring[]
initial_retry_frequencyinteger
max_retry_countinteger
internalboolean
update_datestring

Need the full machine-readable spec? Download the OpenAPI document →

delete/webhooks/{webhook-id}

Delete webhook

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Permanently deletes the specified webhook. This cannot be undone.

Path parameters

Name	Type	Required	Description
webhook-id	string	Yes	—

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

200Webhook deleted.Schema: webhook-response

headersobject
merchantsstring[]
pickupobject
dropoffobject
pickup_partner_location_idsstring
dropoff_partner_location_idsstring
custom_conditionsobject[]
config_idstring
config_namestringrequired
urlstringrequired
statusstring
Values:ACTIVEINACTIVE
entity_typestring
Values:ShipmentReverseShipmentReturnRequest
notify_label_updateboolean
notify_carriyo_label_updateboolean
notify_rma_received_itemsboolean
notify_rma_returned_itemsboolean
notify_statusstring[]
initial_retry_frequencyinteger
max_retry_countinteger
internalboolean
update_datestring

Need the full machine-readable spec? Download the OpenAPI document →

Attributes

A shipment attribute lets the merchant extend the shipment model with additional custom information that isn't natively supported in the Carriyo data model. As a merchant, you define your own custom attributes and reference them on shipments.

5 operations · 0 objects

post/attributes

Create attribute

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Creates a new custom attribute. Once created, the attribute can be set on shipments, addresses, or products depending on attribute_entity_type.

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

Content type: application/jsonSchema: attribute-request

custom_attribute_idstring
Client-supplied identifier for the attribute (e.g. 'pickup_eligibility'). Used as the primary key for the attribute.
attribute_namestringrequired
Attribute name. Maximum 50 characters; lowercase letters and underscores only (e.g. pickup_eligibility).
allowed_valuesstring[]
Permitted values. Required when attribute_type is ENUM; each value must be unique and at most 250 characters. Ignored for other types.
attribute_typestringrequired
The attribute's data type.
Values:STRINGNUMBERENUMBOOLEANMAP
attribute_entity_typestringrequired
Values:SHIPMENTADDRESSPRODUCT

Responses

201Attribute created.Schema: attribute-response

custom_attribute_idstring
attribute_namestringrequired
allowed_valuesstring[]required
attribute_typestringrequired
Values:STRINGNUMBERENUMBOOLEANMAP
attribute_entity_typestring
Values:SHIPMENTADDRESSPRODUCT
indexedboolean
Whether the attribute is indexed for search.

400Validation failed — e.g. `attribute_name` exceeds 50 characters or is not lowercase/underscore format; a required field is missing; or (for `ENUM` type) an `allowed_values` entry exceeds 250 characters or the values are not unique.Schema: error-response

errorsstring[]
Human-readable message(s) describing why the request failed.
statusstring
HTTP status reason (e.g. BAD_REQUEST, NOT_FOUND).
timestampstringformat: date-time

Need the full machine-readable spec? Download the OpenAPI document →

get/attributes

List attributes

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Returns the merchant's custom attributes.

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

200Matching attributes.

custom_attribute_idstring
attribute_namestringrequired
allowed_valuesstring[]required
attribute_typestringrequired
Values:STRINGNUMBERENUMBOOLEANMAP
attribute_entity_typestring
Values:SHIPMENTADDRESSPRODUCT
indexedboolean
Whether the attribute is indexed for search.

Need the full machine-readable spec? Download the OpenAPI document →

get/attributes/{attribute-id}

Get attribute

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Returns the specified custom attribute.

Path parameters

Name	Type	Required	Description
attribute-id	string	Yes	—

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

200Returns the requested attribute.Schema: attribute-response

custom_attribute_idstring
attribute_namestringrequired
allowed_valuesstring[]required
attribute_typestringrequired
Values:STRINGNUMBERENUMBOOLEANMAP
attribute_entity_typestring
Values:SHIPMENTADDRESSPRODUCT
indexedboolean
Whether the attribute is indexed for search.

404No attribute found for the given `attribute-id`.Schema: error-response

errorsstring[]
Human-readable message(s) describing why the request failed.
statusstring
HTTP status reason (e.g. BAD_REQUEST, NOT_FOUND).
timestampstringformat: date-time

Need the full machine-readable spec? Download the OpenAPI document →

put/attributes/{attribute-id}

Update attribute

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Updates the specified custom attribute. Only attribute_type and allowed_values can be changed; other fields are fixed at creation time.

Path parameters

Name	Type	Required	Description
attribute-id	string	Yes	—

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

Content type: application/jsonSchema: attribute-update-request

attribute_typestringrequired
Updated attribute data type.
Values:STRINGNUMBERENUMBOOLEANMAP
allowed_valuesstring[]required
Updated list of allowed values (used when attribute_type is ENUM). Each value must be unique and at most 250 characters.

Responses

200Attribute updated.Schema: attribute-response

custom_attribute_idstring
attribute_namestringrequired
allowed_valuesstring[]required
attribute_typestringrequired
Values:STRINGNUMBERENUMBOOLEANMAP
attribute_entity_typestring
Values:SHIPMENTADDRESSPRODUCT
indexedboolean
Whether the attribute is indexed for search.

400Validation failed — e.g. (for `ENUM` type) an `allowed_values` entry exceeds 250 characters or the values are not unique, or a required field is missing.Schema: error-response

errorsstring[]
Human-readable message(s) describing why the request failed.
statusstring
HTTP status reason (e.g. BAD_REQUEST, NOT_FOUND).
timestampstringformat: date-time

404No attribute found for the given `attribute-id`.Schema: error-response

errorsstring[]
Human-readable message(s) describing why the request failed.
statusstring
HTTP status reason (e.g. BAD_REQUEST, NOT_FOUND).
timestampstringformat: date-time

Need the full machine-readable spec? Download the OpenAPI document →

delete/attributes/{attribute-id}

Delete attribute

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Deletes the specified custom attribute. Existing values on shipments / addresses / products are preserved but the attribute can no longer be set on new ones.

Path parameters

Name	Type	Required	Description
attribute-id	string	Yes	—

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

200Attribute deleted.Schema: attribute-response

custom_attribute_idstring
attribute_namestringrequired
allowed_valuesstring[]required
attribute_typestringrequired
Values:STRINGNUMBERENUMBOOLEANMAP
attribute_entity_typestring
Values:SHIPMENTADDRESSPRODUCT
indexedboolean
Whether the attribute is indexed for search.

404No attribute found for the given `attribute-id`.Schema: error-response

errorsstring[]
Human-readable message(s) describing why the request failed.
statusstring
HTTP status reason (e.g. BAD_REQUEST, NOT_FOUND).
timestampstringformat: date-time

Need the full machine-readable spec? Download the OpenAPI document →

Authentication

Every endpoint uses OAuth 2.0. Exchange your client credentials for an access token:

Get a token

curl -X POST 'https://api.carriyo.com/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "<your-client-id>",
    "client_secret": "<your-client-secret>"
  }'

Then send on every request

Authorization:Bearer <access-token>

tenant-id:<your-tenant-id>

x-api-key:<your-api-key>