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
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
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
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
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
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
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
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
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
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 →

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/{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 →

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 →

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>