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 custom 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 is the kind of delivery service the customer chose, such as "Same Day", "Next Day" or "International", identified by a code you supply; Carriyo derives delivery_type_id from it. A delivery type cannot be changed after creation, and deleting one is permanent. Reading an unknown delivery_type_id answers 200 with an empty body; deleting one answers 400.

4 operations · 0 objects

post/delivery-types

Create delivery type

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Creates a delivery type under the code you supply.

Behavior. A delivery type cannot be changed after creation; to change one, delete it and create it again.

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

delivery_type_idstring
Carriyo-issued identifier, assigned on create.
codestringrequired
Unique code identifying the delivery type. Required; maximum 250 characters; must not already exist in the tenant.
deletedboolean
A stored flag Carriyo does not set; delete removes the delivery type outright.

Responses

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

delivery_type_idstring
Carriyo-issued identifier, assigned on create.
codestringrequired
Unique code identifying the delivery type. Required; maximum 250 characters; must not already exist in the tenant.
deletedboolean
A stored flag Carriyo does not set; delete removes the delivery type outright.

400Schema: error-response

The request was rejected. One of:

code is missing.
code is longer than 250 characters.
a delivery type with this code already exists.

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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 all of the tenant's delivery types in a single unpaged array.

Behavior. The response is sent with Cache-Control: max-age=3600, private, stale-while-revalidate=86400, so a caching client or proxy may keep serving it for up to an hour after a delivery type is created or deleted, and a stale copy for a further 24 hours while it revalidates.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Matching delivery types.

An array of delivery-type-response. Each item has the following fields:

delivery_type_idstring
Carriyo-issued identifier, assigned on create.
codestringrequired
Unique code identifying the delivery type. Required; maximum 250 characters; must not already exist in the tenant.
deletedboolean
A stored flag Carriyo does not set; delete removes the delivery type outright.

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 delivery type with this delivery_type_id.

Behavior. An unknown delivery_type_id is not an error: the call answers 200 with an empty body, so check for a body before parsing.

Path parameters

Name	Type	Required	Description
delivery-type-id	string	Yes	The `delivery_type_id` returned by create or list, not the bare `code`.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200The requested delivery type, or an empty body when the id is unknown.Schema: delivery-type-response

delivery_type_idstring
Carriyo-issued identifier, assigned on create.
codestringrequired
Unique code identifying the delivery type. Required; maximum 250 characters; must not already exist in the tenant.
deletedboolean
A stored flag Carriyo does not set; delete removes the delivery type outright.

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 delivery type with this delivery_type_id. This cannot be undone.

Behavior. The delivery type is removed from any Shopify or WooCommerce connector mapping that references it. Rules are not changed: the delete is refused while an automation, service-level, shipment-costing or capacity rule references the delivery type.

Path parameters

Name	Type	Required	Description
delivery-type-id	string	Yes	The `delivery_type_id` returned by create or list, not the bare `code`.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Delivery type deleted; the response has no body.

400Schema: error-response

The request was rejected. One of:

an automation, service-level, shipment-costing or capacity rule still references the delivery type.
no delivery type has this delivery_type_id.

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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

Locations

A location is a merchant address, usually a store or warehouse, that ships, holds stock, or hands over goods to customers; it has a location_code you supply, a location_name, an address and the merchants that may use it, and is referenced by shipments, orders and return requests. Carriyo assigns location_id. A location can be replaced or patched, and deleting one is soft: status becomes DELETED, the id stays readable, and the location leaves the list. Reading an unknown location_id answers 200 with an empty body; updating or deleting one answers 400.

7 operations · 0 objects

post/locations

Create location

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Creates a location and assigns its location_id.

What to send. Each of these rules is checked before the location is stored:

location_code must be unique among non-deleted locations.
location_name must be unique too, unless your tenant has that check disabled.
merchants names the merchants that may use the location; "_ANY" grants every merchant, and an empty list is rejected.
address1 must be present.
state is required for addresses in US, CA and PH.
fulfillment_zones and fulfillment_radius are mutually exclusive; a radius needs coords and a value greater than 0, zones need neither.

Status. status defaults to ACTIVE when omitted.

Limits. Two limits apply. The total number of non-deleted locations may not exceed your plan's location limit plus a buffer of 100; a request beyond it is rejected. A request that would exceed the plan's ACTIVE limit is stored INACTIVE rather than rejected, so check status in the response.

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_idstring
Carriyo-issued identifier, assigned on create.
location_codestringrequired
Your code for the location. Required; must be unique among non-deleted locations in the tenant.
location_namestringrequired
Display name. Required; must be unique within the tenant unless your tenant has that check disabled.
fulfillment_locationboolean
True when the location can fulfill orders.
inventory_locationboolean
True when the location holds inventory positions.
collection_locationboolean
True when customers can collect from the location. Only such locations are accepted in a delivery option's customer_collection_locations.
fulfillment_zoneslocation-fulfillment-zone[]
Geographies this location can fulfill. Mutually exclusive with fulfillment_radius; setting both is rejected. A location with neither serves everywhere.
fulfillment_radiusdistance
Radius around the location's coordinates within which it can fulfill. Mutually exclusive with fulfillment_zones; the value must be positive and the location must have coords. Only requests carrying customer coordinates can match a radius.
scheduleschedule
Operating schedule for the location.
merchantsstring[]required
Merchant IDs that can use the location, or ["_ANY"] for all. Required and non-empty.
contact_namestring
Contact person at the location. Defaults to the tenant's default contact name when omitted.
contact_emailstring
Contact email. An invalid value is stored and reported as a warning in error_details.
contact_phonestring
Contact phone in E.164 form. An invalid value is stored and reported as a warning in error_details.
company_namestring
Company name shown on labels and documents for the location.
alternate_phonestring
Secondary contact phone.
address1string
First address line. The stored value must be non-empty after your tenant's address model has computed any templated fields.
address2string
Second address line.
citystringrequired
City name. Required.
statestring
State or region code. Required when country is US, CA or PH.
postcodestring
Postal code.
countrystringrequired
Two-letter ISO 3166-1 alpha-2 country code. Required.
coordsnumber[]
Latitude and longitude as [lat, lng]. Exactly two values; latitude -90 to 90, longitude -180 to 180.
areastring
Area or district within the city.
streetstring
Street name.
buildingstring
Building name or number.
floorstring
Floor.
flatstring
Flat, unit or suite.
po_boxstring
PO box.
custom_fieldsobject
Custom attributes with the ADDRESS scope, keyed by attribute name. Each value is an array of strings.
custom_attributesobject
Custom attributes with the LOCATION scope, keyed by attribute name. Values are validated against the attribute definition.
typestring
Whether the address is a business or a residence.
Values:businessresidential
location_typestring
Kind of location.
Values:WAREHOUSESTORE
creation_sourcerequest-source
The system or actor that created the location.
update_sourcerequest-source
The system or actor that last updated the location.
statusstring
Lifecycle status. Defaults to ACTIVE. On create and bulk import a request that would exceed the tenant's ACTIVE limit is stored INACTIVE; on update and patch it is rejected.
Values:ACTIVEINACTIVEDELETEDREDACTED
deletedboolean
Deprecated and never set; read status instead.
creation_datestringformat: date-time
When the location was created.
update_datestringformat: date-time
When the location was last updated.
registration_numbersregistration-number[]
Tax and business registration numbers used on customs documents.
address_codesaddress-code[]
error_detailserror-detail[]
Validation warnings recorded on the last write, such as an invalid contact phone or email.
free_zoneboolean
True when the location is in a free zone. A shipment whose pickup and dropoff differ in free-zone status is treated as cross-border.
shopify_location_idstring
Accepted and ignored; the value is not stored and never returned.

Responses

201Location created.Schema: location-response

location_idstring
Carriyo-issued identifier, assigned on create.
location_codestringrequired
Your code for the location. Required; must be unique among non-deleted locations in the tenant.
location_namestringrequired
Display name. Required; must be unique within the tenant unless your tenant has that check disabled.
fulfillment_locationboolean
True when the location can fulfill orders.
inventory_locationboolean
True when the location holds inventory positions.
collection_locationboolean
True when customers can collect from the location. Only such locations are accepted in a delivery option's customer_collection_locations.
fulfillment_zoneslocation-fulfillment-zone[]
Geographies this location can fulfill. Mutually exclusive with fulfillment_radius; setting both is rejected. A location with neither serves everywhere.
fulfillment_radiusdistance
Radius around the location's coordinates within which it can fulfill. Mutually exclusive with fulfillment_zones; the value must be positive and the location must have coords. Only requests carrying customer coordinates can match a radius.
scheduleschedule
Operating schedule for the location.
merchantsstring[]required
Merchant IDs that can use the location, or ["_ANY"] for all. Required and non-empty.
contact_namestring
Contact person at the location. Defaults to the tenant's default contact name when omitted.
contact_emailstring
Contact email. An invalid value is stored and reported as a warning in error_details.
contact_phonestring
Contact phone in E.164 form. An invalid value is stored and reported as a warning in error_details.
company_namestring
Company name shown on labels and documents for the location.
alternate_phonestring
Secondary contact phone.
address1string
First address line. The stored value must be non-empty after your tenant's address model has computed any templated fields.
address2string
Second address line.
citystringrequired
City name. Required.
statestring
State or region code. Required when country is US, CA or PH.
postcodestring
Postal code.
countrystringrequired
Two-letter ISO 3166-1 alpha-2 country code. Required.
coordsnumber[]
Latitude and longitude as [lat, lng]. Exactly two values; latitude -90 to 90, longitude -180 to 180.
areastring
Area or district within the city.
streetstring
Street name.
buildingstring
Building name or number.
floorstring
Floor.
flatstring
Flat, unit or suite.
po_boxstring
PO box.
custom_fieldsobject
Custom attributes with the ADDRESS scope, keyed by attribute name. Each value is an array of strings.
custom_attributesobject
Custom attributes with the LOCATION scope, keyed by attribute name. Values are validated against the attribute definition.
typestring
Whether the address is a business or a residence.
Values:businessresidential
location_typestring
Kind of location.
Values:WAREHOUSESTORE
creation_sourcerequest-source
The system or actor that created the location.
update_sourcerequest-source
The system or actor that last updated the location.
statusstring
Lifecycle status. Defaults to ACTIVE. On create and bulk import a request that would exceed the tenant's ACTIVE limit is stored INACTIVE; on update and patch it is rejected.
Values:ACTIVEINACTIVEDELETEDREDACTED
deletedboolean
Deprecated and never set; read status instead.
creation_datestringformat: date-time
When the location was created.
update_datestringformat: date-time
When the location was last updated.
registration_numbersregistration-number[]
Tax and business registration numbers used on customs documents.
address_codesaddress-code[]
error_detailserror-detail[]
Validation warnings recorded on the last write, such as an invalid contact phone or email.
free_zoneboolean
True when the location is in a free zone. A shipment whose pickup and dropoff differ in free-zone status is treated as cross-border.

400Schema: error-response

The request was rejected. One of:

location_code is already used by a non-deleted location.
location_name is already in use.
merchants is empty.
address1 is empty.
state is missing for a US, CA or PH address.
both fulfillment_zones and fulfillment_radius are set.
fulfillment_radius is set without coords, or its value is not greater than 0.
the tenant has reached its total location limit.

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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 tenant's locations a page at a time; page is zero-based.

Paging and sorting. page_size * (page + 1) may not exceed 10,000, so the list reaches at most the first 10,000 locations. pagination in the response carries total and page only. Sorting is ignored when search_string is set.

Filtering. Results are limited to the merchants the API key can access. DELETED locations are excluded unless show_deleted=true, so status=DELETED on its own returns nothing.

Response. Items come from the search index and carry fields (geo_coords, tenant, test_data, updated_by_user) that the single-location read does not, alongside your custom location attributes in custom_attributes. cache sets Cache-Control: max-age on the response to that many seconds.

Query parameters

Name	Type	Required	Description
page	integer	No	Page to return, starting at 0. `page_size * (page + 1)` must not exceed 10,000.
page_size	integer	No	Records per page, 0 to 100.
sort_by	string	No	Field to sort by, such as `location_name`, `location_code`, `city`, `country`, `status` or `location_type`. Ignored when `search_string` is set.
sort_direction	string	No	Sort order for `sort_by`.
search_string	string	No	Free-text search over `location_name`, `location_code`, `contact_name` and `company_name`. Results are ranked by relevance and `sort_by` is ignored.
status	array	No	Return only locations in these statuses. Repeatable; values are upper-cased. `DELETED` matches nothing unless `show_deleted` is `true`.
show_deleted	boolean	No	Include `DELETED` locations, which are otherwise excluded whatever `status` says.
location_access	array	No	Restrict results to these location ids. Repeatable; combined with `country_access`, a location matches when it satisfies either.
country_access	array	No	Restrict results to these two-letter country codes. Repeatable.
creation_date_from	string	No	Return only locations created on or after this date, interpreted in the `tzoffset` timezone.
creation_date_to	string	No	Return only locations created on or before this date, interpreted in the `tzoffset` timezone.
tzoffset	integer	No	Offset from UTC in minutes applied to the date filters.
cache	integer	No	When set, the response carries `Cache-Control: private, max-age=<cache>` with this many seconds.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Matching locations.Schema: location-list

itemslocation-response[]
Locations on this page, limited to the merchants the request can access.
paginationobject
Position of the page within the result set.

400Schema: error-response

The request was rejected. One of:

page_size is above 100.
page_size * (page + 1) is above 10,000.

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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 location with this location_id.

Behavior. A deleted location is still returned, with status set to DELETED. An unknown location_id is not an error: the call answers 200 with an empty body, so check for a body before parsing.

Path parameters

Name	Type	Required	Description
location-id	string	Yes	The `location_id` returned by create or list.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200The requested location, or an empty body when the id is unknown.Schema: location-response

location_idstring
Carriyo-issued identifier, assigned on create.
location_codestringrequired
Your code for the location. Required; must be unique among non-deleted locations in the tenant.
location_namestringrequired
Display name. Required; must be unique within the tenant unless your tenant has that check disabled.
fulfillment_locationboolean
True when the location can fulfill orders.
inventory_locationboolean
True when the location holds inventory positions.
collection_locationboolean
True when customers can collect from the location. Only such locations are accepted in a delivery option's customer_collection_locations.
fulfillment_zoneslocation-fulfillment-zone[]
Geographies this location can fulfill. Mutually exclusive with fulfillment_radius; setting both is rejected. A location with neither serves everywhere.
fulfillment_radiusdistance
Radius around the location's coordinates within which it can fulfill. Mutually exclusive with fulfillment_zones; the value must be positive and the location must have coords. Only requests carrying customer coordinates can match a radius.
scheduleschedule
Operating schedule for the location.
merchantsstring[]required
Merchant IDs that can use the location, or ["_ANY"] for all. Required and non-empty.
contact_namestring
Contact person at the location. Defaults to the tenant's default contact name when omitted.
contact_emailstring
Contact email. An invalid value is stored and reported as a warning in error_details.
contact_phonestring
Contact phone in E.164 form. An invalid value is stored and reported as a warning in error_details.
company_namestring
Company name shown on labels and documents for the location.
alternate_phonestring
Secondary contact phone.
address1string
First address line. The stored value must be non-empty after your tenant's address model has computed any templated fields.
address2string
Second address line.
citystringrequired
City name. Required.
statestring
State or region code. Required when country is US, CA or PH.
postcodestring
Postal code.
countrystringrequired
Two-letter ISO 3166-1 alpha-2 country code. Required.
coordsnumber[]
Latitude and longitude as [lat, lng]. Exactly two values; latitude -90 to 90, longitude -180 to 180.
areastring
Area or district within the city.
streetstring
Street name.
buildingstring
Building name or number.
floorstring
Floor.
flatstring
Flat, unit or suite.
po_boxstring
PO box.
custom_fieldsobject
Custom attributes with the ADDRESS scope, keyed by attribute name. Each value is an array of strings.
custom_attributesobject
Custom attributes with the LOCATION scope, keyed by attribute name. Values are validated against the attribute definition.
typestring
Whether the address is a business or a residence.
Values:businessresidential
location_typestring
Kind of location.
Values:WAREHOUSESTORE
creation_sourcerequest-source
The system or actor that created the location.
update_sourcerequest-source
The system or actor that last updated the location.
statusstring
Lifecycle status. Defaults to ACTIVE. On create and bulk import a request that would exceed the tenant's ACTIVE limit is stored INACTIVE; on update and patch it is rejected.
Values:ACTIVEINACTIVEDELETEDREDACTED
deletedboolean
Deprecated and never set; read status instead.
creation_datestringformat: date-time
When the location was created.
update_datestringformat: date-time
When the location was last updated.
registration_numbersregistration-number[]
Tax and business registration numbers used on customs documents.
address_codesaddress-code[]
error_detailserror-detail[]
Validation warnings recorded on the last write, such as an invalid contact phone or email.
free_zoneboolean
True when the location is in a free zone. A shipment whose pickup and dropoff differ in free-zone status is treated as cross-border.

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.

Replaces the location with this location_id with the request body.

What happens. Every field is set to the value supplied; a field omitted from the request is cleared. Only location_id, creation_date, creation_source and the test-data flag are kept from the stored location.

What to send. Create's rules apply to the replacement:

location_code must be unique among non-deleted locations.
location_name must be unique too, unless your tenant has that check disabled.
merchants names the merchants that may use the location; "_ANY" grants every merchant, and an empty list is rejected.
address1 must be present.
state is required for addresses in US, CA and PH.
fulfillment_zones and fulfillment_radius are mutually exclusive; a radius needs coords and a value greater than 0, zones need neither.

Status. The ACTIVE limit applies when the request would make the location ACTIVE: the update is refused, not silently stored INACTIVE as on create.

Path parameters

Name	Type	Required	Description
location-id	string	Yes	The `location_id` returned by create or list.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: location-request

location_idstring
Carriyo-issued identifier, assigned on create.
location_codestringrequired
Your code for the location. Required; must be unique among non-deleted locations in the tenant.
location_namestringrequired
Display name. Required; must be unique within the tenant unless your tenant has that check disabled.
fulfillment_locationboolean
True when the location can fulfill orders.
inventory_locationboolean
True when the location holds inventory positions.
collection_locationboolean
True when customers can collect from the location. Only such locations are accepted in a delivery option's customer_collection_locations.
fulfillment_zoneslocation-fulfillment-zone[]
Geographies this location can fulfill. Mutually exclusive with fulfillment_radius; setting both is rejected. A location with neither serves everywhere.
fulfillment_radiusdistance
Radius around the location's coordinates within which it can fulfill. Mutually exclusive with fulfillment_zones; the value must be positive and the location must have coords. Only requests carrying customer coordinates can match a radius.
scheduleschedule
Operating schedule for the location.
merchantsstring[]required
Merchant IDs that can use the location, or ["_ANY"] for all. Required and non-empty.
contact_namestring
Contact person at the location. Defaults to the tenant's default contact name when omitted.
contact_emailstring
Contact email. An invalid value is stored and reported as a warning in error_details.
contact_phonestring
Contact phone in E.164 form. An invalid value is stored and reported as a warning in error_details.
company_namestring
Company name shown on labels and documents for the location.
alternate_phonestring
Secondary contact phone.
address1string
First address line. The stored value must be non-empty after your tenant's address model has computed any templated fields.
address2string
Second address line.
citystringrequired
City name. Required.
statestring
State or region code. Required when country is US, CA or PH.
postcodestring
Postal code.
countrystringrequired
Two-letter ISO 3166-1 alpha-2 country code. Required.
coordsnumber[]
Latitude and longitude as [lat, lng]. Exactly two values; latitude -90 to 90, longitude -180 to 180.
areastring
Area or district within the city.
streetstring
Street name.
buildingstring
Building name or number.
floorstring
Floor.
flatstring
Flat, unit or suite.
po_boxstring
PO box.
custom_fieldsobject
Custom attributes with the ADDRESS scope, keyed by attribute name. Each value is an array of strings.
custom_attributesobject
Custom attributes with the LOCATION scope, keyed by attribute name. Values are validated against the attribute definition.
typestring
Whether the address is a business or a residence.
Values:businessresidential
location_typestring
Kind of location.
Values:WAREHOUSESTORE
creation_sourcerequest-source
The system or actor that created the location.
update_sourcerequest-source
The system or actor that last updated the location.
statusstring
Lifecycle status. Defaults to ACTIVE. On create and bulk import a request that would exceed the tenant's ACTIVE limit is stored INACTIVE; on update and patch it is rejected.
Values:ACTIVEINACTIVEDELETEDREDACTED
deletedboolean
Deprecated and never set; read status instead.
creation_datestringformat: date-time
When the location was created.
update_datestringformat: date-time
When the location was last updated.
registration_numbersregistration-number[]
Tax and business registration numbers used on customs documents.
address_codesaddress-code[]
error_detailserror-detail[]
Validation warnings recorded on the last write, such as an invalid contact phone or email.
free_zoneboolean
True when the location is in a free zone. A shipment whose pickup and dropoff differ in free-zone status is treated as cross-border.
shopify_location_idstring
Accepted and ignored; the value is not stored and never returned.

Responses

200Location updated.Schema: location-response

location_idstring
Carriyo-issued identifier, assigned on create.
location_codestringrequired
Your code for the location. Required; must be unique among non-deleted locations in the tenant.
location_namestringrequired
Display name. Required; must be unique within the tenant unless your tenant has that check disabled.
fulfillment_locationboolean
True when the location can fulfill orders.
inventory_locationboolean
True when the location holds inventory positions.
collection_locationboolean
True when customers can collect from the location. Only such locations are accepted in a delivery option's customer_collection_locations.
fulfillment_zoneslocation-fulfillment-zone[]
Geographies this location can fulfill. Mutually exclusive with fulfillment_radius; setting both is rejected. A location with neither serves everywhere.
fulfillment_radiusdistance
Radius around the location's coordinates within which it can fulfill. Mutually exclusive with fulfillment_zones; the value must be positive and the location must have coords. Only requests carrying customer coordinates can match a radius.
scheduleschedule
Operating schedule for the location.
merchantsstring[]required
Merchant IDs that can use the location, or ["_ANY"] for all. Required and non-empty.
contact_namestring
Contact person at the location. Defaults to the tenant's default contact name when omitted.
contact_emailstring
Contact email. An invalid value is stored and reported as a warning in error_details.
contact_phonestring
Contact phone in E.164 form. An invalid value is stored and reported as a warning in error_details.
company_namestring
Company name shown on labels and documents for the location.
alternate_phonestring
Secondary contact phone.
address1string
First address line. The stored value must be non-empty after your tenant's address model has computed any templated fields.
address2string
Second address line.
citystringrequired
City name. Required.
statestring
State or region code. Required when country is US, CA or PH.
postcodestring
Postal code.
countrystringrequired
Two-letter ISO 3166-1 alpha-2 country code. Required.
coordsnumber[]
Latitude and longitude as [lat, lng]. Exactly two values; latitude -90 to 90, longitude -180 to 180.
areastring
Area or district within the city.
streetstring
Street name.
buildingstring
Building name or number.
floorstring
Floor.
flatstring
Flat, unit or suite.
po_boxstring
PO box.
custom_fieldsobject
Custom attributes with the ADDRESS scope, keyed by attribute name. Each value is an array of strings.
custom_attributesobject
Custom attributes with the LOCATION scope, keyed by attribute name. Values are validated against the attribute definition.
typestring
Whether the address is a business or a residence.
Values:businessresidential
location_typestring
Kind of location.
Values:WAREHOUSESTORE
creation_sourcerequest-source
The system or actor that created the location.
update_sourcerequest-source
The system or actor that last updated the location.
statusstring
Lifecycle status. Defaults to ACTIVE. On create and bulk import a request that would exceed the tenant's ACTIVE limit is stored INACTIVE; on update and patch it is rejected.
Values:ACTIVEINACTIVEDELETEDREDACTED
deletedboolean
Deprecated and never set; read status instead.
creation_datestringformat: date-time
When the location was created.
update_datestringformat: date-time
When the location was last updated.
registration_numbersregistration-number[]
Tax and business registration numbers used on customs documents.
address_codesaddress-code[]
error_detailserror-detail[]
Validation warnings recorded on the last write, such as an invalid contact phone or email.
free_zoneboolean
True when the location is in a free zone. A shipment whose pickup and dropoff differ in free-zone status is treated as cross-border.

400Schema: error-response

The request was rejected. One of:

location_code is already used by a non-deleted location.
location_name is already in use.
merchants is empty.
address1 is empty.
state is missing for a US, CA or PH address.
both fulfillment_zones and fulfillment_radius are set.
fulfillment_radius is set without coords, or its value is not greater than 0.
the update would exceed the number of ACTIVE locations allowed.
no location has this location_id.

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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 location with this location_id.

What happens. Only the fields present in the request are changed, so a patch cannot clear a field, with one exception: a patch that omits status is applied as status: ACTIVE, so patching an INACTIVE location without status reactivates it. List fields (merchants, address_codes, custom_fields, custom_attributes, fulfillment_zones) are replaced wholesale rather than merged. A non-empty fulfillment_zones clears fulfillment_radius, and a fulfillment_radius clears fulfillment_zones.

What to send. Create's uniqueness and validation rules apply to the merged result, so a patch that would leave the location with a duplicate location_code, an empty address1, or both fulfillment_zones and fulfillment_radius is rejected.

Status. Send status: INACTIVE explicitly to keep an inactive location inactive. Setting status to ACTIVE is refused when the tenant is already at its ACTIVE limit.

Path parameters

Name	Type	Required	Description
location-id	string	Yes	The `location_id` returned by create or list.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

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

location_codestring
Your code for the location. Must stay unique within the tenant.
location_namestring
Display name. Must stay unique within the tenant unless your tenant has that check disabled.
fulfillment_locationboolean
True when the location can fulfill orders.
inventory_locationboolean
True when the location holds inventory positions.
collection_locationboolean
True when customers can collect from the location.
fulfillment_zoneslocation-fulfillment-zone[]
Geographies this location can fulfill. Supplying a non-empty list on a PATCH switches the location to zone coverage and clears any fulfillment_radius; supplying both in one request is rejected. A location with neither serves everywhere.
fulfillment_radiusdistance
Radius around the location's coordinates within which it can fulfill. Supplying it on a PATCH switches the location to radius coverage and clears any fulfillment_zones; the value must be positive and the location must have coords.
scheduleschedule
Operating schedule for the location.
merchantsstring[]
Merchant IDs that can use the location, or ["_ANY"] for all. Changing it is rejected while a rule set that would lose access still references the location.
contact_namestring
Contact person at the location.
contact_emailstring
Contact email. An invalid value is stored and reported as a warning in error_details.
contact_phonestring
Contact phone in E.164 form. An invalid value is stored and reported as a warning in error_details.
alternate_phonestring
Secondary contact phone.
address1string
First address line. The stored value must be non-empty after your tenant's address model has computed any templated fields.
address2string
Second address line.
citystring
City name.
statestring
State or region code. Required when country is US, CA or PH.
postcodestring
Postal code.
countrystring
Two-letter ISO 3166-1 alpha-2 country code.
coordsnumber[]
Latitude and longitude as [lat, lng]. Exactly two values; latitude -90 to 90, longitude -180 to 180.
areastring
Area or district within the city.
streetstring
Street name.
buildingstring
Building name or number.
floorstring
Floor.
flatstring
Flat, unit or suite.
po_boxstring
PO box.
custom_fieldsobject
Custom attributes with the ADDRESS scope, keyed by attribute name. Each value is an array of strings.
custom_attributesobject
Custom attributes with the LOCATION scope, keyed by attribute name. Values are validated against the attribute definition.
address_codesaddress-code[]
typestring
Whether the address is a business or a residence.
Values:businessresidential
statusstring
Lifecycle status. Defaults to ACTIVE when omitted, which reactivates an INACTIVE location; changing to ACTIVE is rejected when the tenant's ACTIVE limit is reached.
Values:ACTIVEINACTIVEDELETEDREDACTED
deletedboolean
Deprecated; ignored on PATCH. Use status instead.
creation_datestringformat: date-time
Accepted and ignored; Carriyo keeps the original creation date.
updateDatestringformat: date-time
Accepted and ignored; Carriyo sets the update date. Named in camelCase on the wire.
free_zoneboolean
True when the location is in a free zone. A shipment whose pickup and dropoff differ in free-zone status is treated as cross-border.

Responses

200Location updated.Schema: location-response

location_idstring
Carriyo-issued identifier, assigned on create.
location_codestringrequired
Your code for the location. Required; must be unique among non-deleted locations in the tenant.
location_namestringrequired
Display name. Required; must be unique within the tenant unless your tenant has that check disabled.
fulfillment_locationboolean
True when the location can fulfill orders.
inventory_locationboolean
True when the location holds inventory positions.
collection_locationboolean
True when customers can collect from the location. Only such locations are accepted in a delivery option's customer_collection_locations.
fulfillment_zoneslocation-fulfillment-zone[]
Geographies this location can fulfill. Mutually exclusive with fulfillment_radius; setting both is rejected. A location with neither serves everywhere.
fulfillment_radiusdistance
Radius around the location's coordinates within which it can fulfill. Mutually exclusive with fulfillment_zones; the value must be positive and the location must have coords. Only requests carrying customer coordinates can match a radius.
scheduleschedule
Operating schedule for the location.
merchantsstring[]required
Merchant IDs that can use the location, or ["_ANY"] for all. Required and non-empty.
contact_namestring
Contact person at the location. Defaults to the tenant's default contact name when omitted.
contact_emailstring
Contact email. An invalid value is stored and reported as a warning in error_details.
contact_phonestring
Contact phone in E.164 form. An invalid value is stored and reported as a warning in error_details.
company_namestring
Company name shown on labels and documents for the location.
alternate_phonestring
Secondary contact phone.
address1string
First address line. The stored value must be non-empty after your tenant's address model has computed any templated fields.
address2string
Second address line.
citystringrequired
City name. Required.
statestring
State or region code. Required when country is US, CA or PH.
postcodestring
Postal code.
countrystringrequired
Two-letter ISO 3166-1 alpha-2 country code. Required.
coordsnumber[]
Latitude and longitude as [lat, lng]. Exactly two values; latitude -90 to 90, longitude -180 to 180.
areastring
Area or district within the city.
streetstring
Street name.
buildingstring
Building name or number.
floorstring
Floor.
flatstring
Flat, unit or suite.
po_boxstring
PO box.
custom_fieldsobject
Custom attributes with the ADDRESS scope, keyed by attribute name. Each value is an array of strings.
custom_attributesobject
Custom attributes with the LOCATION scope, keyed by attribute name. Values are validated against the attribute definition.
typestring
Whether the address is a business or a residence.
Values:businessresidential
location_typestring
Kind of location.
Values:WAREHOUSESTORE
creation_sourcerequest-source
The system or actor that created the location.
update_sourcerequest-source
The system or actor that last updated the location.
statusstring
Lifecycle status. Defaults to ACTIVE. On create and bulk import a request that would exceed the tenant's ACTIVE limit is stored INACTIVE; on update and patch it is rejected.
Values:ACTIVEINACTIVEDELETEDREDACTED
deletedboolean
Deprecated and never set; read status instead.
creation_datestringformat: date-time
When the location was created.
update_datestringformat: date-time
When the location was last updated.
registration_numbersregistration-number[]
Tax and business registration numbers used on customs documents.
address_codesaddress-code[]
error_detailserror-detail[]
Validation warnings recorded on the last write, such as an invalid contact phone or email.
free_zoneboolean
True when the location is in a free zone. A shipment whose pickup and dropoff differ in free-zone status is treated as cross-border.

400Schema: error-response

The request was rejected. One of:

the merged location breaks one of create's rules.
the update would exceed the number of ACTIVE locations allowed.
no location has this location_id.

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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.

Deletes the location with this location_id by setting its status to DELETED.

Behavior. The location keeps its location_id and is still returned by the single-location read, but it leaves the list unless show_deleted=true. Orders and reservations that reference it are not changed. Rules are not changed either: the delete is refused while an automation, service-level, shipment-costing or capacity rule references the location.

Path parameters

Name	Type	Required	Description
location-id	string	Yes	The `location_id` returned by create or list.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Location deleted; the response has no body.

400Schema: error-response

The request was rejected. One of:

an automation, service-level, shipment-costing or capacity rule still references the location.
no location has this location_id.

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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.

Creates or updates up to 20 locations in one request.

What to send. location_requests holds one entry per location, each in the shape of the create request. Entries are matched by location_code: an existing code is updated, a new code is created.

What happens. Rows are processed independently, so one rejected row does not fail the others. Duplicate location_code or location_name values within the request reject those rows. Two limits are computed once before processing: rows beyond the total location limit are rejected, and rows that would exceed the ACTIVE limit are created INACTIVE rather than rejected.

Response. A bare list with one entry per input row, in no guaranteed order; match rows by locationCode (note the camelCase key), which echoes the code from the request. result is created, updated or rejected; reason explains a rejection; location is the saved location when the row was not rejected.

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, one per row in location_requests; order is not guaranteed.

An array of location-bulk-import-response. Each item has the following fields:

resultstring
Whether the row created a new location (created), updated an existing one (updated), or was skipped (rejected).
Values:createdupdatedrejected
locationlocation-response
The saved location when the row was not rejected. Read from the stored entity, so it carries tenant, test_data and updated_by_user, which the create and get responses do not.
reasonstring
Human-readable detail when result is rejected.
locationCodestring
The location_code from the request, echoed on every row so a rejected row can be identified.

400Schema: error-response

The request was rejected. One of:

location_requests is empty.
more than 20 entries in location_requests.

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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

Order Types

An order type is the order journey the customer chose, such as "Home Delivery" or "Click & Collect", identified by a code you supply; Carriyo derives order_type_id from it. An order type cannot be changed after creation, and deleting one is permanent. Reading an unknown order_type_id answers 200 with an empty body; deleting one answers 400.

4 operations · 0 objects

post/order-types

Create order type

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Creates an order type under the code you supply.

Behavior. An order type cannot be changed after creation; to change one, delete it and create it again.

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

order_type_idstring
Carriyo-issued identifier, assigned on create.
codestringrequired
Unique code identifying the order type. Required; maximum 250 characters; must not already exist in the tenant.
deletedboolean
A stored flag Carriyo does not set; delete removes the order type outright.

Responses

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

order_type_idstring
Carriyo-issued identifier, assigned on create.
codestringrequired
Unique code identifying the order type. Required; maximum 250 characters; must not already exist in the tenant.
deletedboolean
A stored flag Carriyo does not set; delete removes the order type outright.

400Schema: error-response

The request was rejected. One of:

code is missing.
code is longer than 250 characters.
an order type with this code already exists.

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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 all of the tenant's order types in a single unpaged array, ordered by code.

Behavior. The response is sent with Cache-Control: max-age=3600, private, stale-while-revalidate=86400, so a caching client or proxy may keep serving it for up to an hour after an order type is created or deleted, and a stale copy for a further 24 hours while it revalidates.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Matching order types.

An array of order-type-response. Each item has the following fields:

order_type_idstring
Carriyo-issued identifier, assigned on create.
codestringrequired
Unique code identifying the order type. Required; maximum 250 characters; must not already exist in the tenant.
deletedboolean
A stored flag Carriyo does not set; delete removes the order type outright.

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 order type with this order_type_id.

Behavior. An unknown order_type_id is not an error: the call answers 200 with an empty body, so check for a body before parsing.

Path parameters

Name	Type	Required	Description
order-type-id	string	Yes	The `order_type_id` returned by create or list, not the bare `code`.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200The requested order type, or an empty body when the id is unknown.Schema: order-type-response

order_type_idstring
Carriyo-issued identifier, assigned on create.
codestringrequired
Unique code identifying the order type. Required; maximum 250 characters; must not already exist in the tenant.
deletedboolean
A stored flag Carriyo does not set; delete removes the order type outright.

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 order type with this order_type_id. This cannot be undone.

Behavior. No connector mapping is touched. Rules are not changed: the delete is refused while an automation, service-level, shipment-costing or capacity rule references the order type.

Path parameters

Name	Type	Required	Description
order-type-id	string	Yes	The `order_type_id` returned by create or list, not the bare `code`.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Order type deleted; the response has no body.

400Schema: error-response

The request was rejected. One of:

an automation, service-level, shipment-costing or capacity rule still references the order type.
no order type has this order_type_id.

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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

Time Slots

A time slot is a window with a from and to time and an optional name that can be offered to the customer for a collection or a delivery when creating a shipment or a return request. time_slot_id is supplied by you and cannot be changed after creation, and deleting a time slot is permanent. An unknown time_slot_id answers 404 on read and delete.

4 operations · 0 objects

post/time-slots

Create time slot

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Creates a time slot under the time_slot_id you supply.

Behavior. time_slot_id must be unique, and to must be later than from. A time slot cannot be changed after creation; to change one, delete it and create it again.

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
Your identifier for the time slot. Required and non-blank.
namestring
Display name for the slot.
fromstringrequired
Start of the window as HH:00, 24-hour clock. Required; minutes must be 00.
tostringrequired
End of the window as HH:00, 24-hour clock. Required; must be later than from.

Responses

201Time slot created.Schema: time-slot

time_slot_idstringrequired
Your identifier for the time slot. Required and non-blank.
namestring
Display name for the slot.
fromstringrequired
Start of the window as HH:00, 24-hour clock. Required; minutes must be 00.
tostringrequired
End of the window as HH:00, 24-hour clock. Required; must be later than from.

400Schema: error-response

The request was rejected. One of:

time_slot_id already exists.
to is not later than from.

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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 all of the tenant's time slots in a single unpaged array.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Matching time slots.

An array of time-slot. Each item has the following fields:

time_slot_idstringrequired
Your identifier for the time slot. Required and non-blank.
namestring
Display name for the slot.
fromstringrequired
Start of the window as HH:00, 24-hour clock. Required; minutes must be 00.
tostringrequired
End of the window as HH:00, 24-hour clock. Required; 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 time slot with this time_slot_id.

Path parameters

Name	Type	Required	Description
time-slot-id	string	Yes	The `time_slot_id` you supplied on create.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200The requested time slot.Schema: time-slot

time_slot_idstringrequired
Your identifier for the time slot. Required and non-blank.
namestring
Display name for the slot.
fromstringrequired
Start of the window as HH:00, 24-hour clock. Required; minutes must be 00.
tostringrequired
End of the window as HH:00, 24-hour clock. Required; must be later than from.

404No time slot has this time_slot_id.Schema: error-response

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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 time slot with this time_slot_id. This cannot be undone.

Behavior. No rule references a time slot, so the delete is never refused on that ground.

Path parameters

Name	Type	Required	Description
time-slot-id	string	Yes	The `time_slot_id` you supplied on create.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Time slot deleted; the response has no body.

404No time slot has this time_slot_id.Schema: error-response

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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; it carries the carrier account that fulfills it, its shipping_fee, its delivery_estimation, and the eligibility conditions (geography, order value, weight, payment type, product categories) under which it is offered. It is configured here and evaluated for shoppers by the Storefront API. Carriyo assigns id; an option can be replaced, and deleting one is permanent. An unknown id answers 404 on read, update and delete.

5 operations · 0 objects

post/delivery-options

Create delivery option

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Creates a delivery option with its carrier account, schedule, fee and eligibility conditions, and assigns its id.

What to send. code, name, delivery_method, status and merchant are required; status has no default. code must be unique within the tenant.

Silent adjustments. PAID is the ordinary shipping_fee.pricing_strategy and is stored as sent; Carriyo adjusts the following on save without reporting it, so read the response rather than assuming the request was stored as sent:

a shipping_fee.pricing_strategy of PASS_THROUGH with no carrier_account_id is stored as FREE_OF_COST with the pricing cleared.
delivery_method: DIGITAL clears carrier_account_id.
any delivery_method other than COLLECTION clears customer_collection_locations and customer_collection_max_distance.
any delivery_method other than DELIVERY clears customer_delivery_max_distance.

Status. status is stored exactly as sent; DELETED and REDACTED are accepted like any other value and are not treated specially.

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.
codestringrequired
Merchant-supplied code used as the option's stable identifier (e.g. EXPRESS_AE). Must be unique within the tenant.
namestringrequired
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_methodstringrequired
Delivery method (home delivery, customer pickup, or digital fulfillment).
Values:DELIVERYCOLLECTIONDIGITAL
merchantstringrequired
Merchant the option belongs to.
carrier_account_idstring
Carrier account that fulfills shipments booked via this option. Cleared on save for a DIGITAL option, and must grant access to merchant.
statusstringrequired
Option status. Required; only ACTIVE options are evaluated by the storefront delivery-options endpoints.
Values:ACTIVEINACTIVEDELETEDREDACTED
scheduleschedule
Working days / blackout dates for this option.
shipping_feeshipping-fee
Pricing configuration.
delivery_estimationdelivery-estimation
Customer-facing delivery-time estimation configuration.
order_valueinteger-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
Order-level category condition: shows or hides the option for the whole order. The option is offered only when at least one item in the order has an includes category, and withheld when any item has an excludes category. To scope the option per item instead, use item_product_categories.
item_product_categoriesorder-category-condition
Item-level category condition: scopes the option per item instead of showing or hiding it for the whole order. With includes, the option applies only to items whose category is listed; with excludes, items with a listed category are excluded and every other item qualifies. Non-matching items are marked unavailable for the option in storefront delivery-options responses (availability: NONE, fulfillable_quantity: 0), and an option no cart item matches is not returned. An item with no category fails a non-empty includes list and passes an excludes-only condition. Matching is case-insensitive and ignores surrounding whitespace.
fulfillment_locationsstring[]
Carriyo location codes/IDs eligible to fulfill this option. An empty or omitted list means any fulfillment-enabled location, regardless of country — each location's own fulfillment coverage (zones or radius), merchant access, and stock availability still apply.
customer_collection_locationsstring[]
For COLLECTION methods: IDs of the Carriyo locations the customer can collect from. Only locations with the collection_location flag enabled are accepted. An empty or omitted list means any location: at storefront read time the option resolves to every ACTIVE collection-enabled location the merchant can use, restricted to the customer's country. An explicit list is honored as-is — it is not filtered by the customer's country, so a merchant can deliberately include cross-border collection points (unlike the any-location behaviour, which is always same-country).
customer_collection_max_distancedistance
For COLLECTION methods: maximum distance from the customer to a candidate collection location. Enforced only when the storefront request supplies the customer's coordinates — it is a proximity bound, not a country bound, so a radius near a border can legitimately include cross-border locations from an explicit list.
customer_delivery_max_distancedistance
For DELIVERY methods: maximum straight-line distance from the customer's coordinates to a fulfillment location; the option is offered only when one of its locations is within it. Without customer coordinates it is not offered. value must be a positive number, and unit is required.
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.
codestringrequired
Merchant-supplied code used as the option's stable identifier (e.g. EXPRESS_AE). Must be unique within the tenant.
namestringrequired
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_methodstringrequired
Delivery method (home delivery, customer pickup, or digital fulfillment).
Values:DELIVERYCOLLECTIONDIGITAL
merchantstringrequired
Merchant the option belongs to.
carrier_account_idstring
Carrier account that fulfills shipments booked via this option. Cleared on save for a DIGITAL option, and must grant access to merchant.
statusstringrequired
Option status. Required; only ACTIVE options are evaluated by the storefront delivery-options endpoints.
Values:ACTIVEINACTIVEDELETEDREDACTED
scheduleschedule
Working days / blackout dates for this option.
shipping_feeshipping-fee
Pricing configuration.
delivery_estimationdelivery-estimation
Customer-facing delivery-time estimation configuration.
order_valueinteger-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
Order-level category condition: shows or hides the option for the whole order. The option is offered only when at least one item in the order has an includes category, and withheld when any item has an excludes category. To scope the option per item instead, use item_product_categories.
item_product_categoriesorder-category-condition
Item-level category condition: scopes the option per item instead of showing or hiding it for the whole order. With includes, the option applies only to items whose category is listed; with excludes, items with a listed category are excluded and every other item qualifies. Non-matching items are marked unavailable for the option in storefront delivery-options responses (availability: NONE, fulfillable_quantity: 0), and an option no cart item matches is not returned. An item with no category fails a non-empty includes list and passes an excludes-only condition. Matching is case-insensitive and ignores surrounding whitespace.
fulfillment_locationsstring[]
Carriyo location codes/IDs eligible to fulfill this option. An empty or omitted list means any fulfillment-enabled location, regardless of country — each location's own fulfillment coverage (zones or radius), merchant access, and stock availability still apply.
customer_collection_locationsstring[]
For COLLECTION methods: IDs of the Carriyo locations the customer can collect from. Only locations with the collection_location flag enabled are accepted. An empty or omitted list means any location: at storefront read time the option resolves to every ACTIVE collection-enabled location the merchant can use, restricted to the customer's country. An explicit list is honored as-is — it is not filtered by the customer's country, so a merchant can deliberately include cross-border collection points (unlike the any-location behaviour, which is always same-country).
customer_collection_max_distancedistance
For COLLECTION methods: maximum distance from the customer to a candidate collection location. Enforced only when the storefront request supplies the customer's coordinates — it is a proximity bound, not a country bound, so a radius near a border can legitimately include cross-border locations from an explicit list.
customer_delivery_max_distancedistance
For DELIVERY methods: maximum straight-line distance from the customer's coordinates to a fulfillment location; the option is offered only when one of its locations is within it. Without customer coordinates it is not offered. value must be a positive number, and unit is required.
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).

400Schema: error-response

The request was rejected. One of:

code, name, delivery_method, status or merchant is missing.
code already exists in the tenant.
customer_delivery_max_distance on a DELIVERY option has no unit, or a value that is missing or not a positive number.

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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 tenant's delivery options a page at a time; page is 1-based.

Parameters. This list's query parameters are camelCase (pageSize, carrierAccountIds, locationIds, customerCountry, searchString), unlike the location list. The pagination parameter is a flag; the pagination object in the response reports the page position.

Paging. pageSize defaults to 10 with no maximum, and an out-of-range page returns an empty list. With pagination=false the whole filtered set comes back unpaged, and the response reports page 0 and page_size 0 with the real total. Options come back in storage order; there is no sequence field to order them by.

The 100-option ceiling. Only the first 100 stored options are read, and every filter, total and the paging operate on that slice, so an account with more than 100 options cannot reach the rest through this list.

Query parameters

Name	Type	Required	Description
page	integer	No	Page to return, starting at 1. An out-of-range page returns an empty list.
pageSize	integer	No	Records per page, with no maximum. Named in camelCase; the response echoes it as `page_size`.
pagination	boolean	No	Set to `false` to return the whole filtered set unpaged; the response then reports `page` 0 and `page_size` 0 with the real `total`.
merchant	string	No	Return only options whose `merchant` is exactly this value; options with merchant `_ANY` always pass.
status	array	No	Return only options in any of these statuses. Repeatable; exact match.
carrierAccountIds	array	No	Return only options whose `carrier_account_id` is exactly one of these values.
locationIds	array	No	Return only options whose `fulfillment_locations` or `customer_collection_locations` include at least one of these location ids.
customerCountry	string	No	Return only options whose `customer` condition explicitly lists this country (ISO 3166-1 alpha-2). An option with no `customer` condition is excluded.
searchString	string	No	Case-insensitive contains match on `name` and `code`.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Matching delivery options.Schema: delivery-option-list

itemsdelivery-option[]
Delivery options on this page.
paginationpagination
Position of a page within a result set.

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 delivery option with this id.

Path parameters

Name	Type	Required	Description
delivery-option-id	string	Yes	The `id` returned by create or list.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200The requested delivery option.Schema: delivery-option

idstring
Carriyo-issued identifier. Server-assigned on create.
codestringrequired
Merchant-supplied code used as the option's stable identifier (e.g. EXPRESS_AE). Must be unique within the tenant.
namestringrequired
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_methodstringrequired
Delivery method (home delivery, customer pickup, or digital fulfillment).
Values:DELIVERYCOLLECTIONDIGITAL
merchantstringrequired
Merchant the option belongs to.
carrier_account_idstring
Carrier account that fulfills shipments booked via this option. Cleared on save for a DIGITAL option, and must grant access to merchant.
statusstringrequired
Option status. Required; only ACTIVE options are evaluated by the storefront delivery-options endpoints.
Values:ACTIVEINACTIVEDELETEDREDACTED
scheduleschedule
Working days / blackout dates for this option.
shipping_feeshipping-fee
Pricing configuration.
delivery_estimationdelivery-estimation
Customer-facing delivery-time estimation configuration.
order_valueinteger-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
Order-level category condition: shows or hides the option for the whole order. The option is offered only when at least one item in the order has an includes category, and withheld when any item has an excludes category. To scope the option per item instead, use item_product_categories.
item_product_categoriesorder-category-condition
Item-level category condition: scopes the option per item instead of showing or hiding it for the whole order. With includes, the option applies only to items whose category is listed; with excludes, items with a listed category are excluded and every other item qualifies. Non-matching items are marked unavailable for the option in storefront delivery-options responses (availability: NONE, fulfillable_quantity: 0), and an option no cart item matches is not returned. An item with no category fails a non-empty includes list and passes an excludes-only condition. Matching is case-insensitive and ignores surrounding whitespace.
fulfillment_locationsstring[]
Carriyo location codes/IDs eligible to fulfill this option. An empty or omitted list means any fulfillment-enabled location, regardless of country — each location's own fulfillment coverage (zones or radius), merchant access, and stock availability still apply.
customer_collection_locationsstring[]
For COLLECTION methods: IDs of the Carriyo locations the customer can collect from. Only locations with the collection_location flag enabled are accepted. An empty or omitted list means any location: at storefront read time the option resolves to every ACTIVE collection-enabled location the merchant can use, restricted to the customer's country. An explicit list is honored as-is — it is not filtered by the customer's country, so a merchant can deliberately include cross-border collection points (unlike the any-location behaviour, which is always same-country).
customer_collection_max_distancedistance
For COLLECTION methods: maximum distance from the customer to a candidate collection location. Enforced only when the storefront request supplies the customer's coordinates — it is a proximity bound, not a country bound, so a radius near a border can legitimately include cross-border locations from an explicit list.
customer_delivery_max_distancedistance
For DELIVERY methods: maximum straight-line distance from the customer's coordinates to a fulfillment location; the option is offered only when one of its locations is within it. Without customer coordinates it is not offered. value must be a positive number, and unit is required.
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).

404No delivery option has this id.Schema: error-response

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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.

Replaces the delivery option with this id with the request body.

What happens. Every field is set to the value supplied; a field omitted from the request is cleared. Only id, the tenant and creation_date are kept from the stored option.

a shipping_fee.pricing_strategy of PASS_THROUGH with no carrier_account_id is stored as FREE_OF_COST with the pricing cleared.
delivery_method: DIGITAL clears carrier_account_id.
any delivery_method other than COLLECTION clears customer_collection_locations and customer_collection_max_distance.
any delivery_method other than DELIVERY clears customer_delivery_max_distance.

Status. status is stored exactly as sent; DELETED and REDACTED are accepted like any other value and are not treated specially.

Code. Uniqueness is checked only when code changes by more than its case; a case-only rename is not checked and can leave two options with the same code.

Path parameters

Name	Type	Required	Description
delivery-option-id	string	Yes	The `id` returned by create or list.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: delivery-optionrequired

idstring
Carriyo-issued identifier. Server-assigned on create.
codestringrequired
Merchant-supplied code used as the option's stable identifier (e.g. EXPRESS_AE). Must be unique within the tenant.
namestringrequired
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_methodstringrequired
Delivery method (home delivery, customer pickup, or digital fulfillment).
Values:DELIVERYCOLLECTIONDIGITAL
merchantstringrequired
Merchant the option belongs to.
carrier_account_idstring
Carrier account that fulfills shipments booked via this option. Cleared on save for a DIGITAL option, and must grant access to merchant.
statusstringrequired
Option status. Required; only ACTIVE options are evaluated by the storefront delivery-options endpoints.
Values:ACTIVEINACTIVEDELETEDREDACTED
scheduleschedule
Working days / blackout dates for this option.
shipping_feeshipping-fee
Pricing configuration.
delivery_estimationdelivery-estimation
Customer-facing delivery-time estimation configuration.
order_valueinteger-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
Order-level category condition: shows or hides the option for the whole order. The option is offered only when at least one item in the order has an includes category, and withheld when any item has an excludes category. To scope the option per item instead, use item_product_categories.
item_product_categoriesorder-category-condition
Item-level category condition: scopes the option per item instead of showing or hiding it for the whole order. With includes, the option applies only to items whose category is listed; with excludes, items with a listed category are excluded and every other item qualifies. Non-matching items are marked unavailable for the option in storefront delivery-options responses (availability: NONE, fulfillable_quantity: 0), and an option no cart item matches is not returned. An item with no category fails a non-empty includes list and passes an excludes-only condition. Matching is case-insensitive and ignores surrounding whitespace.
fulfillment_locationsstring[]
Carriyo location codes/IDs eligible to fulfill this option. An empty or omitted list means any fulfillment-enabled location, regardless of country — each location's own fulfillment coverage (zones or radius), merchant access, and stock availability still apply.
customer_collection_locationsstring[]
For COLLECTION methods: IDs of the Carriyo locations the customer can collect from. Only locations with the collection_location flag enabled are accepted. An empty or omitted list means any location: at storefront read time the option resolves to every ACTIVE collection-enabled location the merchant can use, restricted to the customer's country. An explicit list is honored as-is — it is not filtered by the customer's country, so a merchant can deliberately include cross-border collection points (unlike the any-location behaviour, which is always same-country).
customer_collection_max_distancedistance
For COLLECTION methods: maximum distance from the customer to a candidate collection location. Enforced only when the storefront request supplies the customer's coordinates — it is a proximity bound, not a country bound, so a radius near a border can legitimately include cross-border locations from an explicit list.
customer_delivery_max_distancedistance
For DELIVERY methods: maximum straight-line distance from the customer's coordinates to a fulfillment location; the option is offered only when one of its locations is within it. Without customer coordinates it is not offered. value must be a positive number, and unit is required.
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.
codestringrequired
Merchant-supplied code used as the option's stable identifier (e.g. EXPRESS_AE). Must be unique within the tenant.
namestringrequired
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_methodstringrequired
Delivery method (home delivery, customer pickup, or digital fulfillment).
Values:DELIVERYCOLLECTIONDIGITAL
merchantstringrequired
Merchant the option belongs to.
carrier_account_idstring
Carrier account that fulfills shipments booked via this option. Cleared on save for a DIGITAL option, and must grant access to merchant.
statusstringrequired
Option status. Required; only ACTIVE options are evaluated by the storefront delivery-options endpoints.
Values:ACTIVEINACTIVEDELETEDREDACTED
scheduleschedule
Working days / blackout dates for this option.
shipping_feeshipping-fee
Pricing configuration.
delivery_estimationdelivery-estimation
Customer-facing delivery-time estimation configuration.
order_valueinteger-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
Order-level category condition: shows or hides the option for the whole order. The option is offered only when at least one item in the order has an includes category, and withheld when any item has an excludes category. To scope the option per item instead, use item_product_categories.
item_product_categoriesorder-category-condition
Item-level category condition: scopes the option per item instead of showing or hiding it for the whole order. With includes, the option applies only to items whose category is listed; with excludes, items with a listed category are excluded and every other item qualifies. Non-matching items are marked unavailable for the option in storefront delivery-options responses (availability: NONE, fulfillable_quantity: 0), and an option no cart item matches is not returned. An item with no category fails a non-empty includes list and passes an excludes-only condition. Matching is case-insensitive and ignores surrounding whitespace.
fulfillment_locationsstring[]
Carriyo location codes/IDs eligible to fulfill this option. An empty or omitted list means any fulfillment-enabled location, regardless of country — each location's own fulfillment coverage (zones or radius), merchant access, and stock availability still apply.
customer_collection_locationsstring[]
For COLLECTION methods: IDs of the Carriyo locations the customer can collect from. Only locations with the collection_location flag enabled are accepted. An empty or omitted list means any location: at storefront read time the option resolves to every ACTIVE collection-enabled location the merchant can use, restricted to the customer's country. An explicit list is honored as-is — it is not filtered by the customer's country, so a merchant can deliberately include cross-border collection points (unlike the any-location behaviour, which is always same-country).
customer_collection_max_distancedistance
For COLLECTION methods: maximum distance from the customer to a candidate collection location. Enforced only when the storefront request supplies the customer's coordinates — it is a proximity bound, not a country bound, so a radius near a border can legitimately include cross-border locations from an explicit list.
customer_delivery_max_distancedistance
For DELIVERY methods: maximum straight-line distance from the customer's coordinates to a fulfillment location; the option is offered only when one of its locations is within it. Without customer coordinates it is not offered. value must be a positive number, and unit is required.
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).

400Schema: error-response

The request was rejected. One of:

code is changed to one that already exists in the tenant.
customer_delivery_max_distance on a DELIVERY option has no unit, or a value that is missing or not a positive number.

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

404No delivery option has this id.Schema: error-response

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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 delivery option with this id. This cannot be undone.

Behavior. Answers 204 with no body.

Path parameters

Name	Type	Required	Description
delivery-option-id	string	Yes	The `id` returned by create or list.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

204Delivery option deleted; the response has no body.

404No delivery option has this id.Schema: error-response

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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

Webhooks

A webhook is a configuration under which Carriyo pushes events for one entity_type to your endpoint as JSON over HTTPS: the target url, custom headers, the merchants it applies to, and its triggers. A trigger is a notify_status value or a notify_* flag, and every event delivered names its trigger in the trigger header. Any response outside the 2xx range is a failed delivery; Carriyo retries automatically, and events that still fail can be read and retriggered through the failed-events operations. Carriyo assigns config_id; a configuration can be replaced, and deleting one is permanent. Reading an unknown config_id answers 200 with an empty body; updating or deleting one answers 400.

7 operations · 0 objects

post/webhooks

Create webhook

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Creates a webhook configuration that delivers events for one entity_type to your endpoint, and assigns its config_id.

What to send.

config_name, url and entity_type are required.
config_name must be unique among configurations that share a merchant.
merchants is required for every entity_type except INVENTORY, where whatever you send is replaced by ["_ANY"]; each merchant named must exist.
url is stored as sent and not checked for format, so a malformed URL is accepted and only fails at delivery.
headers holds any custom headers sent with each delivery, such as the credentials your endpoint expects.

Triggers. A configuration must have at least one trigger. What counts depends on entity_type:

INVENTORY — notify_status must be exactly ["ALL_INVENTORY_UPDATES"].
SHIPMENT (and the deprecated REVERSE_SHIPMENT) — a non-empty notify_status, or one of notify_label_update, notify_carriyo_label_update, notify_commercial_invoice_update, notify_promised_delivery_date, notify_scheduled_collection, notify_scheduled_delivery.
RETURN_REQUEST — a non-empty notify_status, or notify_rma_received_items or notify_rma_returned_items.
ORDER, ORDER_CHANGE_REQUEST, ORDER_DELIVERY_CLAIM, COLLECTION — a non-empty notify_status.

Status and limits. status defaults to ACTIVE. An INACTIVE configuration receives nothing and does not count toward the ACTIVE limit.

Two limits apply. The total number of configurations may not exceed your plan's webhook limit plus a buffer of 10; a request beyond it is rejected. A request that would exceed the plan's ACTIVE limit is stored INACTIVE rather than rejected, so check status in the response.

Delivery and retries. Carriyo waits up to 30 seconds to connect and 30 seconds for the response, treats any response outside the 2xx range as a failed delivery, retries three times, and retries five more times when extended_webhook_retries_enabled is set on the configuration.

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

config_idstring
Carriyo-issued identifier, assigned on create.
config_namestringrequired
Display name. Required and non-empty; must be unique among configurations that share a merchant.
urlstringrequired
Endpoint Carriyo posts events to. Required.
headersobject
Custom HTTP headers sent with every delivery. Defaults to {}.
statusstring
Lifecycle status. Defaults to ACTIVE; on create a request that would exceed the tenant's ACTIVE limit is stored INACTIVE, and an INACTIVE configuration receives nothing.
Values:ACTIVEINACTIVEDELETEDREDACTED
merchantsstring[]
Merchant IDs the webhook applies to, or ["_ANY"] for all. Required and non-empty for every entity_type except INVENTORY, where it is ignored and stored as ["_ANY"].
entity_typestringrequired
Entity the webhook listens on. Required. REVERSE_SHIPMENT is deprecated; use SHIPMENT, which covers forward and reverse shipments.
Values:SHIPMENTREVERSE_SHIPMENTRETURN_REQUESTORDERORDER_CHANGE_REQUESTORDER_DELIVERY_CLAIMCOLLECTIONINVENTORY
shipment_typestring
Accepted and stored; the delivery router does not currently filter on it.
notify_label_updateboolean
Shipment trigger. Fire when the default label is generated.
notify_carriyo_label_updateboolean
Shipment trigger. Fire when the Carriyo label is generated.
notify_commercial_invoice_updateboolean
Shipment trigger. Fire when the commercial invoice is generated.
notify_rma_received_itemsboolean
Return request trigger. Fire when returned items are received.
notify_rma_returned_itemsboolean
Return request trigger. Fire when items are marked as returned.
notify_promised_delivery_dateboolean
Shipment trigger. Fire when the promised delivery date changes.
notify_scheduled_collectionboolean
Shipment trigger. Fire when the scheduled collection date changes.
notify_scheduled_deliveryboolean
Shipment trigger. Fire when the scheduled delivery date changes.
notify_statusstring[]
Status events to deliver, by entity_type. SHIPMENT and REVERSE_SHIPMENT take shipment status values and need at least one entry unless a shipment notify_* trigger is true; RETURN_REQUEST takes return request status values and needs at least one entry unless notify_rma_received_items or notify_rma_returned_items is true; ORDER, ORDER_CHANGE_REQUEST, ORDER_DELIVERY_CLAIM and COLLECTION need at least one non-blank entry; INVENTORY must be exactly ["ALL_INVENTORY_UPDATES"].
dropoff_v2country-states-condition-v2
Deliver only when the dropoff address falls in matching countries, states, cities and areas.
dropoff_partner_location_idsstring-condition
Deliver only for matching dropoff location IDs. Every listed location must be ACTIVE.
pickup_v2country-states-condition-v2
Deliver only when the pickup address falls in matching countries, states, cities and areas.
pickup_partner_location_idsstring-condition
Deliver only for matching pickup location IDs. Every listed location must be ACTIVE.
delivery_typestring-condition
Deliver only for matching delivery type codes.
order_typestring-condition
Deliver only for matching order type codes.
creation_source_typestring-condition
Deliver only for entities created by matching source types, such as api or shopify_connector.
creation_source_idstring-condition
Deliver only for entities created by matching source IDs.
update_source_typestring-condition
Deliver only for entities last updated by matching source types.
update_source_idstring-condition
Deliver only for entities last updated by matching source IDs.
custom_conditions_v2custom-condition-v2[]
Deliver only when the entity's custom attributes match. Each attribute_name must be a defined custom attribute, and for ENUM attributes every value must be one of its allowed_values.
internalboolean
Marks a Carriyo-internal webhook. Internal webhooks do not count toward the tenant's webhook limit.
creation_datestringformat: date-time
When the webhook was created, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.
update_datestringformat: date-time
When the webhook was last updated, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.
authenticationwebhook-authentication
How Carriyo authenticates to your endpoint.
extended_webhook_retries_enabledboolean
Per configuration. When true, a failed delivery is retried 8 times (3 at 1, 3 and 5 minutes, then 5 more at 1, 3, 5, 8 and 13 hours) instead of the default 3.

Responses

201Webhook created.Schema: webhook-response

config_idstring
Carriyo-issued identifier, assigned on create.
config_namestringrequired
Display name. Required and non-empty; must be unique among configurations that share a merchant.
urlstringrequired
Endpoint Carriyo posts events to. Required.
headersobject
Custom HTTP headers sent with every delivery. Defaults to {}.
statusstring
Lifecycle status. Defaults to ACTIVE; on create a request that would exceed the tenant's ACTIVE limit is stored INACTIVE, and an INACTIVE configuration receives nothing.
Values:ACTIVEINACTIVEDELETEDREDACTED
merchantsstring[]
Merchant IDs the webhook applies to, or ["_ANY"] for all. Required and non-empty for every entity_type except INVENTORY, where it is ignored and stored as ["_ANY"].
entity_typestringrequired
Entity the webhook listens on. Required. REVERSE_SHIPMENT is deprecated; use SHIPMENT, which covers forward and reverse shipments.
Values:SHIPMENTREVERSE_SHIPMENTRETURN_REQUESTORDERORDER_CHANGE_REQUESTORDER_DELIVERY_CLAIMCOLLECTIONINVENTORY
shipment_typestring
Accepted and stored; the delivery router does not currently filter on it.
notify_label_updateboolean
Shipment trigger. Fire when the default label is generated.
notify_carriyo_label_updateboolean
Shipment trigger. Fire when the Carriyo label is generated.
notify_commercial_invoice_updateboolean
Shipment trigger. Fire when the commercial invoice is generated.
notify_rma_received_itemsboolean
Return request trigger. Fire when returned items are received.
notify_rma_returned_itemsboolean
Return request trigger. Fire when items are marked as returned.
notify_promised_delivery_dateboolean
Shipment trigger. Fire when the promised delivery date changes.
notify_scheduled_collectionboolean
Shipment trigger. Fire when the scheduled collection date changes.
notify_scheduled_deliveryboolean
Shipment trigger. Fire when the scheduled delivery date changes.
notify_statusstring[]
Status events to deliver, by entity_type. SHIPMENT and REVERSE_SHIPMENT take shipment status values and need at least one entry unless a shipment notify_* trigger is true; RETURN_REQUEST takes return request status values and needs at least one entry unless notify_rma_received_items or notify_rma_returned_items is true; ORDER, ORDER_CHANGE_REQUEST, ORDER_DELIVERY_CLAIM and COLLECTION need at least one non-blank entry; INVENTORY must be exactly ["ALL_INVENTORY_UPDATES"].
dropoff_v2country-states-condition-v2
Deliver only when the dropoff address falls in matching countries, states, cities and areas.
dropoff_partner_location_idsstring-condition
Deliver only for matching dropoff location IDs. Every listed location must be ACTIVE.
pickup_v2country-states-condition-v2
Deliver only when the pickup address falls in matching countries, states, cities and areas.
pickup_partner_location_idsstring-condition
Deliver only for matching pickup location IDs. Every listed location must be ACTIVE.
delivery_typestring-condition
Deliver only for matching delivery type codes.
order_typestring-condition
Deliver only for matching order type codes.
creation_source_typestring-condition
Deliver only for entities created by matching source types, such as api or shopify_connector.
creation_source_idstring-condition
Deliver only for entities created by matching source IDs.
update_source_typestring-condition
Deliver only for entities last updated by matching source types.
update_source_idstring-condition
Deliver only for entities last updated by matching source IDs.
custom_conditions_v2custom-condition-v2[]
Deliver only when the entity's custom attributes match. Each attribute_name must be a defined custom attribute, and for ENUM attributes every value must be one of its allowed_values.
internalboolean
Marks a Carriyo-internal webhook. Internal webhooks do not count toward the tenant's webhook limit.
creation_datestringformat: date-time
When the webhook was created, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.
update_datestringformat: date-time
When the webhook was last updated, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.
authenticationwebhook-authentication
How Carriyo authenticates to your endpoint.
extended_webhook_retries_enabledboolean
Per configuration. When true, a failed delivery is retried 8 times (3 at 1, 3 and 5 minutes, then 5 more at 1, 3, 5, 8 and 13 hours) instead of the default 3.

400Schema: error-response

The request was rejected. One of:

config_name, url or entity_type is missing.
no trigger is set for the chosen entity_type.
merchants is missing for an entity_type other than INVENTORY.
merchants names a merchant that does not exist.
config_name is already used by a configuration that shares a merchant.
the tenant has reached its total webhook limit.

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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 all of the tenant's webhook configurations in a single unpaged array.

Behavior. There are no query parameters. The array holds configurations of every status, INACTIVE included, and is limited to the merchants the API key can access.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Matching webhooks.

An array of webhook-response. Each item has the following fields:

config_idstring
Carriyo-issued identifier, assigned on create.
config_namestringrequired
Display name. Required and non-empty; must be unique among configurations that share a merchant.
urlstringrequired
Endpoint Carriyo posts events to. Required.
headersobject
Custom HTTP headers sent with every delivery. Defaults to {}.
statusstring
Lifecycle status. Defaults to ACTIVE; on create a request that would exceed the tenant's ACTIVE limit is stored INACTIVE, and an INACTIVE configuration receives nothing.
Values:ACTIVEINACTIVEDELETEDREDACTED
merchantsstring[]
Merchant IDs the webhook applies to, or ["_ANY"] for all. Required and non-empty for every entity_type except INVENTORY, where it is ignored and stored as ["_ANY"].
entity_typestringrequired
Entity the webhook listens on. Required. REVERSE_SHIPMENT is deprecated; use SHIPMENT, which covers forward and reverse shipments.
Values:SHIPMENTREVERSE_SHIPMENTRETURN_REQUESTORDERORDER_CHANGE_REQUESTORDER_DELIVERY_CLAIMCOLLECTIONINVENTORY
shipment_typestring
Accepted and stored; the delivery router does not currently filter on it.
notify_label_updateboolean
Shipment trigger. Fire when the default label is generated.
notify_carriyo_label_updateboolean
Shipment trigger. Fire when the Carriyo label is generated.
notify_commercial_invoice_updateboolean
Shipment trigger. Fire when the commercial invoice is generated.
notify_rma_received_itemsboolean
Return request trigger. Fire when returned items are received.
notify_rma_returned_itemsboolean
Return request trigger. Fire when items are marked as returned.
notify_promised_delivery_dateboolean
Shipment trigger. Fire when the promised delivery date changes.
notify_scheduled_collectionboolean
Shipment trigger. Fire when the scheduled collection date changes.
notify_scheduled_deliveryboolean
Shipment trigger. Fire when the scheduled delivery date changes.
notify_statusstring[]
Status events to deliver, by entity_type. SHIPMENT and REVERSE_SHIPMENT take shipment status values and need at least one entry unless a shipment notify_* trigger is true; RETURN_REQUEST takes return request status values and needs at least one entry unless notify_rma_received_items or notify_rma_returned_items is true; ORDER, ORDER_CHANGE_REQUEST, ORDER_DELIVERY_CLAIM and COLLECTION need at least one non-blank entry; INVENTORY must be exactly ["ALL_INVENTORY_UPDATES"].
dropoff_v2country-states-condition-v2
Deliver only when the dropoff address falls in matching countries, states, cities and areas.
dropoff_partner_location_idsstring-condition
Deliver only for matching dropoff location IDs. Every listed location must be ACTIVE.
pickup_v2country-states-condition-v2
Deliver only when the pickup address falls in matching countries, states, cities and areas.
pickup_partner_location_idsstring-condition
Deliver only for matching pickup location IDs. Every listed location must be ACTIVE.
delivery_typestring-condition
Deliver only for matching delivery type codes.
order_typestring-condition
Deliver only for matching order type codes.
creation_source_typestring-condition
Deliver only for entities created by matching source types, such as api or shopify_connector.
creation_source_idstring-condition
Deliver only for entities created by matching source IDs.
update_source_typestring-condition
Deliver only for entities last updated by matching source types.
update_source_idstring-condition
Deliver only for entities last updated by matching source IDs.
custom_conditions_v2custom-condition-v2[]
Deliver only when the entity's custom attributes match. Each attribute_name must be a defined custom attribute, and for ENUM attributes every value must be one of its allowed_values.
internalboolean
Marks a Carriyo-internal webhook. Internal webhooks do not count toward the tenant's webhook limit.
creation_datestringformat: date-time
When the webhook was created, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.
update_datestringformat: date-time
When the webhook was last updated, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.
authenticationwebhook-authentication
How Carriyo authenticates to your endpoint.
extended_webhook_retries_enabledboolean
Per configuration. When true, a failed delivery is retried 8 times (3 at 1, 3 and 5 minutes, then 5 more at 1, 3, 5, 8 and 13 hours) instead of the default 3.

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

get/webhooks/failed-events

Retrieve failed webhook events

Returns the events of one webhook configuration that failed delivery within a time window.

What to send. webhook_id, start_date and end_date are all required. The window may span at most 1 day; give both dates in UTC as yyyy-MM-dd'T'HH:mm:ss.SSSXXX (for example 2023-03-22T10:15:30.123Z). Failed events expire after 30 days, so an older window returns nothing.

What counts as failed. A failed webhook event is one where Carriyo received a response outside the 2xx range from your endpoint. Events remain here after the automatic retries are exhausted.

Response. original_failure_count is the number of events that failed in the window and current_failure_count the number still failed; failed_events lists those. The response is not paged. When no event failed in the window the call still answers 200, with error_message set instead of the counts; check it before reading them.

Query parameters

Name	Type	Required	Description
webhook_id	string	Yes	The `config_id` of the webhook configuration.
start_date	string	Yes	Start of the window, UTC, as `yyyy-MM-dd'T'HH:mm:ss.SSSXXX` (a literal `Z` or `+00:00` offset; `+0000` is rejected).
end_date	string	Yes	End of the window, same format. At most 1 day after `start_date`.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Failed events in the window, or error_message when there are none.Schema: webhook-failed-events-success-response

original_failure_countinteger
Events that failed within the window.
current_failure_countinteger
Of those, events still in the failed state.
failed_eventswebhook-event[]
The events still failed.
error_messagestring
Present instead of the counts when no events match the input.

400webhook_id, start_date or end_date is missing.Schema: webhook-failed-events-error-response

500

The request was rejected. One of:

the window is longer than 1 day.
a date is malformed.

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

post/webhooks/retrigger-failed-events

Retrigger failed webhook events

Queues failed events of one webhook configuration for delivery again.

What to send. webhook_id is required in both modes, plus one of two selections:

by entity: entity_ids and trigger name the events to resend, where trigger is the value delivered in the failed event's trigger header; this mode wins whenever entity_ids is non-empty.
by window: start_date and end_date bound a window of at most 1 day, in UTC as yyyy-MM-dd'T'HH:mm:ss.SSSXXX; failed events expire after 30 days, so an older window returns nothing.

What counts as failed. A failed webhook event is one where Carriyo received a response outside the 2xx range from your endpoint.

What happens. Delivery is asynchronous: 200 means the events were queued, not that they were delivered. An event whose last attempt succeeded, or whose payload is no longer available, is skipped and does not appear in retriggered_events. In window mode, a window holding more than 1,000 failed events is not retriggered at all; narrow the window and call again.

Response. original_failure_count is the number of events that failed for the selection and retriggered_count the number queued; retriggered_events lists those. A body with neither selection answers 200 with an empty object.

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
The config_id of the webhook configuration. Required in both modes.
start_datestringformat: date-time
Start of the range, UTC, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX (a literal Z or +00:00 offset; +0000 is rejected). Required with end_date for the date-range mode; ignored when entity_ids is set.
end_datestringformat: date-time
End of the range, same format. At most 1 day after start_date.
entity_idsstring[]
IDs of the entities of the configuration's entity_type whose events failed. When non-empty, this mode is used and the date range is ignored.
triggerstring
Event to retrigger for entity_ids, as delivered in the trigger header of the failed event. Required when entity_ids is set.

Responses

200Events queued for delivery, error_message when the window holds too many, or an empty object when neither selection was sent.Schema: webhook-retrigger-failed-events-success-response

original_failure_countinteger
Events that failed within the window or for the given entities.
retriggered_countinteger
Events retriggered by this call; in date-range mode at most 1,000.
retriggered_eventswebhook-event[]
The events retriggered.
error_messagestring
Present instead of the counts when no events match the input, or, in date-range mode, more than 1,000 events match.

400start_date and end_date are present but webhook_id is empty.Schema: webhook-retrigger-failed-events-error-response

500

The request was rejected. One of:

entity_ids is given but trigger or webhook_id is missing.
the window is longer than 1 day.
a date is malformed.

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 webhook configuration with this config_id.

Behavior. An unknown config_id is not an error: the call answers 200 with an empty body, so check for a body before parsing.

Path parameters

Name	Type	Required	Description
webhook-id	string	Yes	The `config_id` returned by create or list.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200The requested webhook, or an empty body when the id is unknown.Schema: webhook-response

config_idstring
Carriyo-issued identifier, assigned on create.
config_namestringrequired
Display name. Required and non-empty; must be unique among configurations that share a merchant.
urlstringrequired
Endpoint Carriyo posts events to. Required.
headersobject
Custom HTTP headers sent with every delivery. Defaults to {}.
statusstring
Lifecycle status. Defaults to ACTIVE; on create a request that would exceed the tenant's ACTIVE limit is stored INACTIVE, and an INACTIVE configuration receives nothing.
Values:ACTIVEINACTIVEDELETEDREDACTED
merchantsstring[]
Merchant IDs the webhook applies to, or ["_ANY"] for all. Required and non-empty for every entity_type except INVENTORY, where it is ignored and stored as ["_ANY"].
entity_typestringrequired
Entity the webhook listens on. Required. REVERSE_SHIPMENT is deprecated; use SHIPMENT, which covers forward and reverse shipments.
Values:SHIPMENTREVERSE_SHIPMENTRETURN_REQUESTORDERORDER_CHANGE_REQUESTORDER_DELIVERY_CLAIMCOLLECTIONINVENTORY
shipment_typestring
Accepted and stored; the delivery router does not currently filter on it.
notify_label_updateboolean
Shipment trigger. Fire when the default label is generated.
notify_carriyo_label_updateboolean
Shipment trigger. Fire when the Carriyo label is generated.
notify_commercial_invoice_updateboolean
Shipment trigger. Fire when the commercial invoice is generated.
notify_rma_received_itemsboolean
Return request trigger. Fire when returned items are received.
notify_rma_returned_itemsboolean
Return request trigger. Fire when items are marked as returned.
notify_promised_delivery_dateboolean
Shipment trigger. Fire when the promised delivery date changes.
notify_scheduled_collectionboolean
Shipment trigger. Fire when the scheduled collection date changes.
notify_scheduled_deliveryboolean
Shipment trigger. Fire when the scheduled delivery date changes.
notify_statusstring[]
Status events to deliver, by entity_type. SHIPMENT and REVERSE_SHIPMENT take shipment status values and need at least one entry unless a shipment notify_* trigger is true; RETURN_REQUEST takes return request status values and needs at least one entry unless notify_rma_received_items or notify_rma_returned_items is true; ORDER, ORDER_CHANGE_REQUEST, ORDER_DELIVERY_CLAIM and COLLECTION need at least one non-blank entry; INVENTORY must be exactly ["ALL_INVENTORY_UPDATES"].
dropoff_v2country-states-condition-v2
Deliver only when the dropoff address falls in matching countries, states, cities and areas.
dropoff_partner_location_idsstring-condition
Deliver only for matching dropoff location IDs. Every listed location must be ACTIVE.
pickup_v2country-states-condition-v2
Deliver only when the pickup address falls in matching countries, states, cities and areas.
pickup_partner_location_idsstring-condition
Deliver only for matching pickup location IDs. Every listed location must be ACTIVE.
delivery_typestring-condition
Deliver only for matching delivery type codes.
order_typestring-condition
Deliver only for matching order type codes.
creation_source_typestring-condition
Deliver only for entities created by matching source types, such as api or shopify_connector.
creation_source_idstring-condition
Deliver only for entities created by matching source IDs.
update_source_typestring-condition
Deliver only for entities last updated by matching source types.
update_source_idstring-condition
Deliver only for entities last updated by matching source IDs.
custom_conditions_v2custom-condition-v2[]
Deliver only when the entity's custom attributes match. Each attribute_name must be a defined custom attribute, and for ENUM attributes every value must be one of its allowed_values.
internalboolean
Marks a Carriyo-internal webhook. Internal webhooks do not count toward the tenant's webhook limit.
creation_datestringformat: date-time
When the webhook was created, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.
update_datestringformat: date-time
When the webhook was last updated, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.
authenticationwebhook-authentication
How Carriyo authenticates to your endpoint.
extended_webhook_retries_enabledboolean
Per configuration. When true, a failed delivery is retried 8 times (3 at 1, 3 and 5 minutes, then 5 more at 1, 3, 5, 8 and 13 hours) instead of the default 3.

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.

Replaces the webhook configuration with this config_id with the request body.

What happens. Every field is set to the value supplied; a field omitted from the request is cleared. Only config_id and creation_date are kept from the stored configuration. The ACTIVE limit is not applied on update: a request that moves status to ACTIVE at the limit is stored ACTIVE regardless.

What to send.

config_name, url and entity_type are required; config_name is not checked for uniqueness on update.
merchants is required for every entity_type except INVENTORY, where whatever you send is replaced by ["_ANY"]; each merchant named must exist.
url is stored as sent and not checked for format, so a malformed URL is accepted and only fails at delivery.

Triggers. A configuration must have at least one trigger. What counts depends on entity_type:

INVENTORY — notify_status must be exactly ["ALL_INVENTORY_UPDATES"].
SHIPMENT (and the deprecated REVERSE_SHIPMENT) — a non-empty notify_status, or one of notify_label_update, notify_carriyo_label_update, notify_commercial_invoice_update, notify_promised_delivery_date, notify_scheduled_collection, notify_scheduled_delivery.
RETURN_REQUEST — a non-empty notify_status, or notify_rma_received_items or notify_rma_returned_items.
ORDER, ORDER_CHANGE_REQUEST, ORDER_DELIVERY_CLAIM, COLLECTION — a non-empty notify_status.

Response. Unlike create, get and list, this call returns the stored configuration with mostly camelCase keys (configId, configName, notifyStatus, entityType, updateDate), while creation_date, updated_by_user, authentication and extended_webhook_retries_enabled stay snake_case; this is a known defect. Do not parse it with the same model as the other webhook responses.

Path parameters

Name	Type	Required	Description
webhook-id	string	Yes	The `config_id` returned by create or list.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: webhook-request

config_idstring
Carriyo-issued identifier, assigned on create.
config_namestringrequired
Display name. Required and non-empty; must be unique among configurations that share a merchant.
urlstringrequired
Endpoint Carriyo posts events to. Required.
headersobject
Custom HTTP headers sent with every delivery. Defaults to {}.
statusstring
Lifecycle status. Defaults to ACTIVE; on create a request that would exceed the tenant's ACTIVE limit is stored INACTIVE, and an INACTIVE configuration receives nothing.
Values:ACTIVEINACTIVEDELETEDREDACTED
merchantsstring[]
Merchant IDs the webhook applies to, or ["_ANY"] for all. Required and non-empty for every entity_type except INVENTORY, where it is ignored and stored as ["_ANY"].
entity_typestringrequired
Entity the webhook listens on. Required. REVERSE_SHIPMENT is deprecated; use SHIPMENT, which covers forward and reverse shipments.
Values:SHIPMENTREVERSE_SHIPMENTRETURN_REQUESTORDERORDER_CHANGE_REQUESTORDER_DELIVERY_CLAIMCOLLECTIONINVENTORY
shipment_typestring
Accepted and stored; the delivery router does not currently filter on it.
notify_label_updateboolean
Shipment trigger. Fire when the default label is generated.
notify_carriyo_label_updateboolean
Shipment trigger. Fire when the Carriyo label is generated.
notify_commercial_invoice_updateboolean
Shipment trigger. Fire when the commercial invoice is generated.
notify_rma_received_itemsboolean
Return request trigger. Fire when returned items are received.
notify_rma_returned_itemsboolean
Return request trigger. Fire when items are marked as returned.
notify_promised_delivery_dateboolean
Shipment trigger. Fire when the promised delivery date changes.
notify_scheduled_collectionboolean
Shipment trigger. Fire when the scheduled collection date changes.
notify_scheduled_deliveryboolean
Shipment trigger. Fire when the scheduled delivery date changes.
notify_statusstring[]
Status events to deliver, by entity_type. SHIPMENT and REVERSE_SHIPMENT take shipment status values and need at least one entry unless a shipment notify_* trigger is true; RETURN_REQUEST takes return request status values and needs at least one entry unless notify_rma_received_items or notify_rma_returned_items is true; ORDER, ORDER_CHANGE_REQUEST, ORDER_DELIVERY_CLAIM and COLLECTION need at least one non-blank entry; INVENTORY must be exactly ["ALL_INVENTORY_UPDATES"].
dropoff_v2country-states-condition-v2
Deliver only when the dropoff address falls in matching countries, states, cities and areas.
dropoff_partner_location_idsstring-condition
Deliver only for matching dropoff location IDs. Every listed location must be ACTIVE.
pickup_v2country-states-condition-v2
Deliver only when the pickup address falls in matching countries, states, cities and areas.
pickup_partner_location_idsstring-condition
Deliver only for matching pickup location IDs. Every listed location must be ACTIVE.
delivery_typestring-condition
Deliver only for matching delivery type codes.
order_typestring-condition
Deliver only for matching order type codes.
creation_source_typestring-condition
Deliver only for entities created by matching source types, such as api or shopify_connector.
creation_source_idstring-condition
Deliver only for entities created by matching source IDs.
update_source_typestring-condition
Deliver only for entities last updated by matching source types.
update_source_idstring-condition
Deliver only for entities last updated by matching source IDs.
custom_conditions_v2custom-condition-v2[]
Deliver only when the entity's custom attributes match. Each attribute_name must be a defined custom attribute, and for ENUM attributes every value must be one of its allowed_values.
internalboolean
Marks a Carriyo-internal webhook. Internal webhooks do not count toward the tenant's webhook limit.
creation_datestringformat: date-time
When the webhook was created, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.
update_datestringformat: date-time
When the webhook was last updated, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.
authenticationwebhook-authentication
How Carriyo authenticates to your endpoint.
extended_webhook_retries_enabledboolean
Per configuration. When true, a failed delivery is retried 8 times (3 at 1, 3 and 5 minutes, then 5 more at 1, 3, 5, 8 and 13 hours) instead of the default 3.

Responses

200Webhook updated. The body is the stored configuration in its mixed camelCase form, not the webhook-response shape.Schema: webhook-update-response

400Schema: error-response

The request was rejected. One of:

config_name, url or entity_type is missing.
no trigger is set for the chosen entity_type.
merchants is missing for an entity_type other than INVENTORY.
merchants names a merchant that does not exist.
no webhook configuration has this config_id.

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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 webhook configuration with this config_id. This cannot be undone.

Behavior. Retries already scheduled for the configuration are not cancelled; when they fire they find no active configuration and deliver nothing.

Path parameters

Name	Type	Required	Description
webhook-id	string	Yes	The `config_id` returned by create or list.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Webhook deleted; the response has no body.

400No webhook configuration has this config_id.Schema: error-response

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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

Attributes

A custom attribute extends the Carriyo data model with a field of your own: defined once with a name, a type and the scopes it can be set on, then referenced by name on orders, shipments, returns, products, addresses or locations. Creating and deleting custom attributes requires a subscription that includes them, attribute_name is fixed once created, and deleting one is permanent. An unknown custom_attribute_id answers 404 on read, update and delete.

5 operations · 0 objects

post/attributes

Create custom attribute

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Creates a custom attribute and assigns its custom_attribute_id.

What to send. attribute_name, attribute_type and attribute_scopes are required; attribute_name must be unique and cannot be changed after creation. allowed_values is required when attribute_type is ENUM and is discarded for every other type.

Precondition. Creating a custom attribute requires a subscription that includes custom attributes.

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
Ignored on create; Carriyo generates the identifier.
attribute_namestringrequired
Attribute name. Required; lowercase letters and underscores only, at most 50 characters, and unique within the tenant.
attribute_typestringrequired
The attribute's data type. Required; matched case-insensitively.
Values:STRINGNUMBERENUMBOOLEANMAP
attribute_scopesstring[]required
Entities the attribute can be set on. Required and non-empty; matched case-insensitively.
allowed_valuesstring[]
Permitted values. Required when attribute_type is ENUM; each value must be unique, non-blank and at most 250 characters. Ignored for other types.

Responses

201Custom attribute created.Schema: attribute-response

custom_attribute_idstring
Carriyo-generated identifier for the attribute.
attribute_namestring
Attribute name.
attribute_typestring
The attribute's data type.
Values:STRINGNUMBERENUMBOOLEANMAP
attribute_scopesstring[]
Entities the attribute can be set on.
allowed_valuesstring[]
Present when attribute_type is ENUM; omitted for other types.

400Schema: error-response

The request was rejected. One of:

the tenant's subscription does not include custom attributes.
attribute_name already exists.
an ADDRESS-scoped attribute_name clashes with a built-in address field.
attribute_type is ENUM and allowed_values is missing.
allowed_values contains a blank value.
allowed_values contains a duplicate value.

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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

get/attributes

List custom attributes

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Returns all of the tenant's custom attributes in a single unpaged array.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Matching custom attributes.

An array of attribute-response. Each item has the following fields:

custom_attribute_idstring
Carriyo-generated identifier for the attribute.
attribute_namestring
Attribute name.
attribute_typestring
The attribute's data type.
Values:STRINGNUMBERENUMBOOLEANMAP
attribute_scopesstring[]
Entities the attribute can be set on.
allowed_valuesstring[]
Present when attribute_type is ENUM; omitted for other types.

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

get/attributes/{attribute-id}

Get custom attribute

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Returns the custom attribute with this custom_attribute_id.

Path parameters

Name	Type	Required	Description
attribute-id	string	Yes	The `custom_attribute_id` returned by create or list.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200The requested custom attribute.Schema: attribute-response

custom_attribute_idstring
Carriyo-generated identifier for the attribute.
attribute_namestring
Attribute name.
attribute_typestring
The attribute's data type.
Values:STRINGNUMBERENUMBOOLEANMAP
attribute_scopesstring[]
Entities the attribute can be set on.
allowed_valuesstring[]
Present when attribute_type is ENUM; omitted for other types.

404No custom attribute has this custom_attribute_id.Schema: error-response

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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

put/attributes/{attribute-id}

Update custom attribute

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Updates the custom attribute with this custom_attribute_id.

What changes. attribute_name is fixed at creation; attribute_type, attribute_scopes and allowed_values can be changed. allowed_values replaces the stored list, and removing a value that an automation, service-level, shipment-costing or capacity rule still references is refused.

Precondition. Unlike create and delete, update does not require the subscription to include custom attributes.

Path parameters

Name	Type	Required	Description
attribute-id	string	Yes	The `custom_attribute_id` returned by create or list.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

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

attribute_typestringrequired
Updated data type. Required; matched case-insensitively.
Values:STRINGNUMBERENUMBOOLEANMAP
attribute_scopesstring[]required
Updated scopes. Required and non-empty.
allowed_valuesstring[]
Updated permitted values. Required when attribute_type is ENUM; each value must be unique, non-blank and at most 250 characters, and values still used by rule conditions cannot be removed.

Responses

200Custom attribute updated.Schema: attribute-response

custom_attribute_idstring
Carriyo-generated identifier for the attribute.
attribute_namestring
Attribute name.
attribute_typestring
The attribute's data type.
Values:STRINGNUMBERENUMBOOLEANMAP
attribute_scopesstring[]
Entities the attribute can be set on.
allowed_valuesstring[]
Present when attribute_type is ENUM; omitted for other types.

400Schema: error-response

The request was rejected. One of:

allowed_values no longer contains a value that a rule references.
attribute_type is ENUM and allowed_values is missing.
allowed_values contains a blank value.
allowed_values contains a duplicate value.

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

404No custom attribute has this custom_attribute_id.Schema: error-response

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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

delete/attributes/{attribute-id}

Delete custom attribute

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Permanently deletes the custom attribute with this custom_attribute_id. This cannot be undone.

Behavior. Values already stored on every entity in its scopes are preserved, but the attribute can no longer be set on new ones. Rules are not changed: the delete is refused while an automation, service-level, shipment-costing or capacity rule references the attribute. Deleting requires a subscription that includes custom attributes.

Path parameters

Name	Type	Required	Description
attribute-id	string	Yes	The `custom_attribute_id` returned by create or list.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Custom attribute deleted; the response has no body.

400Schema: error-response

The request was rejected. One of:

an automation, service-level, shipment-costing or capacity rule still references the attribute.
the tenant's subscription does not include custom attributes.

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

404No custom attribute has this custom_attribute_id.Schema: error-response

errorsstring[]
Human-readable messages describing why the request failed.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status reason, such as BAD_REQUEST or NOT_FOUND.
timestampstringformat: date-time
When the error was produced, as yyyy-MM-dd'T'HH:mm:ss.SSSXXX.

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>