API reference

Shipping Setup API

The Carriyo Shipping Setup API manages the configuration the shipping engine reads on every booking: carrier accounts, shipping rules, service levels, carrier networks, and costing profiles. These resources are set up once per merchant and updated infrequently.

Use the Carriyo Dashboard for shipping setup

Setting up carriers, service levels, networks, costing, and automation rules is infrequent, low-volume work — for most merchants, it’s one-time onboarding plus occasional changes. Consider using the Carriyo Dashboard instead: it validates inputs, surfaces required fields contextually, shows live previews of routing decisions, 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 KeySpecshipping-setup.yaml

Carrier Accounts

A carrier account in Carriyo holds the settings for a given account with your chosen carrier. The information in the carrier account varies by carrier and usually includes details such as the account number, the API credentials (API key, username, password), and the chosen service type.

If you're a business that uses multiple carriers for shipping, you'll have multiple carrier accounts. For instance, if you have an account with DHL and UPS, you'll create two carrier accounts in Carriyo (one for each carrier) with the mandatory settings needed to book and track your shipments. You can also configure multiple carrier accounts in Carriyo for the same carrier when you hold multiple accounts with them across service types or countries.

7 operations · 0 objects

post/carrier-accounts

Create carrier account

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Create a new carrier account for the merchant. The account holds the credentials and configuration Carriyo uses to book shipments with that carrier.

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: carrier-account-request

carrier_account_idstring
Unique identifier of the carrier account.
parentobject
Parent account reference for child (e.g. Click-n-Ship) accounts.
merchantsstring[]
Merchant IDs allowed to use this account.
carrier_account_namestring
carrierstring
Carrier code (e.g. QUIQUP, DHL).
account_countrystring
ISO 3166-1 alpha-2 country code for the account.
account_currencystring
ISO 4217 currency code for the account.
daily_capacity_idstring
in_flight_capacity_idstring
costing_profile_idstring
network_idstring
propertyobject
Carrier-specific credential and configuration key-value pairs.
carrier_custom_attributesobject
document_mappingsobject
location_mappingsobject
Maps partner location IDs to carrier-specific location codes (hub codes, branch IDs, outlet codes, etc.).
labelobject
service_scheduleobject
Per-service pickup schedule configuration.
carrier_contact_emailstring
Contact email address for the carrier, stored on the account.
auto_ready_to_shipboolean
auto_schedule_pickupboolean
When true, a carrier pickup is scheduled automatically when a shipment is booked on this account, where the carrier supports pickup scheduling.
auto_return_confirmedboolean
auto_translate_to_englishboolean
use_carrier_costing_apiboolean
service_namestring
service_descriptionstring
delivery_promisestring
estimated_daysinteger
shipping_cost_markup_percentagenumberformat: double
statusstring
Values:ACTIVEINACTIVEDELETED
deletedboolean
Deprecated. Use status instead (DELETED).
generic_carrierboolean
packagingobject
unique_identifierstring
assetsobject

Responses

200Carrier account created.Schema: carrier-account-object

carrier_account_idstring
Unique identifier of the carrier account.
parentobject
Parent account reference for child (e.g. Click-n-Ship) accounts.
merchantsstring[]
Merchant IDs allowed to use this account.
carrier_account_namestring
carrierstring
Carrier code (e.g. QUIQUP, DHL).
account_countrystring
ISO 3166-1 alpha-2 country code for the account.
account_currencystring
ISO 4217 currency code for the account.
daily_capacity_idstring
in_flight_capacity_idstring
costing_profile_idstring
network_idstring
propertyobject
Carrier-specific credential and configuration key-value pairs.
carrier_custom_attributesobject
document_mappingsobject
location_mappingsobject
Maps partner location IDs to carrier-specific location codes (hub codes, branch IDs, outlet codes, etc.).
labelobject
service_scheduleobject
Per-service pickup schedule configuration.
carrier_contact_emailstring
Contact email address for the carrier, stored on the account.
auto_ready_to_shipboolean
auto_schedule_pickupboolean
When true, a carrier pickup is scheduled automatically when a shipment is booked on this account, where the carrier supports pickup scheduling.
auto_return_confirmedboolean
auto_translate_to_englishboolean
use_carrier_costing_apiboolean
service_namestring
service_descriptionstring
delivery_promisestring
estimated_daysinteger
shipping_cost_markup_percentagenumberformat: double
statusstring
Values:ACTIVEINACTIVEDELETED
deletedboolean
Deprecated. Use status instead (DELETED).
generic_carrierboolean
packagingobject
unique_identifierstring
assetsobject
creation_datestringformat: date-time
update_datestringformat: date-time
deletion_datestringformat: date-time
integration_statusesobject
Present when integration_status=true on GET. Maps capability name to integration check result.

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

get/carrier-accounts

List carrier accounts

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

List carrier accounts configured for your tenant. The response is a paginated wrapper (items plus pagination), not a JSON array at the root.

By default, active and inactive accounts are included. Pass status (e.g. ACTIVE) to narrow the list. Deleted accounts are never returned. Only ACTIVE accounts can be used to book shipments.

Use page and page_size to page through results; the first page is page=0. Set pagination=false to ignore both and return the first 100 matches in a single response.

Query parameters

Name	Type	Required	Description
status	array	No	Filter by account status. Repeat the parameter or pass multiple values to match more than one status (e.g. `status=ACTIVE&status=INACTIVE`).
page	integer	No	Page number, starting at `0`. Default `0`.
page_size	integer	No	Number of accounts per page. Default `10`, maximum `100`.
pagination	boolean	No	When `false`, `page` and `page_size` are ignored and the first 100 matches are returned in one response.
search_string	string	No	Free-text search across account name and carrier.
carrier	array	No	Filter by carrier code (e.g. `DHL`, `QUIQUP`).
carrier_id	array	No	Filter by carrier account ID.
carrier_account_name	array	No	Filter by carrier account display name. The match is exact.
country	array	No	Filter by ISO 3166-1 alpha-2 account country.
is_live	boolean	No	Filter by live vs test credentials in account properties.
exclude_carrier	string	No	Leave out accounts of this carrier code.
sort_by	string	No	Field to sort by. `carrier_account_name`, `carrier` and `country` are supported. Ignored when `search_string` is set.
sort_direction	string	No	Sort order. Default `DESC`.

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

200Paginated carrier accounts. The response is an object with items and pagination, not a bare array.Schema: carrier-account-page

itemscarrier-account-object[]required
Carrier accounts for the current page, or the first 100 matches when pagination=false.
paginationobjectrequired

400

The request was rejected. One of:

page or page_size is not a number.
page_size is negative or above 100.
page_size * (page + 1) exceeds 10,000.

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

get/carrier-accounts/statistics

List carrier accounts with statistics

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

List carrier accounts together with their activity timestamps: last booking, last error, and the last real-time and sync tracking updates.

Query parameters. This operation reads its multi-word parameters in camelCase (pageSize, searchString, carrierId, accountName, accountCountry, isLive, sortBy). The snake_case spellings used by List carrier accounts are accepted but ignored here.

Paging. Pages start at 1 here, not at 0 as on List carrier accounts.

What you get back. Each item is the account as Get carrier account returns it with statistics=true. A timestamp is null until the event it records has happened.

Query parameters

Name	Type	Required	Description
status	array	No	Filter by account status. Repeat the parameter to match more than one status (e.g. `status=ACTIVE&status=INACTIVE`).
page	integer	No	Page number (1-based). Default `1`.
pageSize	integer	No	Number of accounts per page. Default `10`.
pagination	boolean	No	When `false`, all matching accounts are returned in `items` and `pagination.page` / `pagination.page_size` are `0`.
searchString	string	No	Free-text search across account name and related fields.
carrier	array	No	Filter by carrier code (e.g. `DHL`, `QUIQUP`).
carrierId	array	No	Filter by carrier account ID.
accountName	array	No	Filter by carrier account display name.
accountCountry	array	No	Filter by ISO 3166-1 alpha-2 account country.
isLive	boolean	No	Filter by live vs test credentials in account properties.
excludeCarrier	string	No	Leave out accounts of this carrier code.
sortBy	string	No	Carrier account field to sort by, in snake_case, such as `carrier_account_name`, `account_country`, `carrier`, `status` or `update_date`. A field that cannot be sorted returns an empty list instead of an error.
sortDirection	string	No	Sort order.

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

200Paginated carrier accounts, each with its activity timestamps. The response is an object with items and pagination, not a bare array.Schema: carrier-account-statistics-page

itemscarrier-account-statistics-object[]required
Carrier accounts for the current page, or all matches when pagination=false.
paginationobjectrequired

400

The request was rejected. One of:

page is below 1.
pageSize is negative.

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

post/carrier-accounts/shipping-rates

Get shipping rates

Rate-shop a prospective shipment across a caller-supplied list of carrier accounts. Pass the shipment details plus the carrier_accounts to quote, and Carriyo returns one rate per account. The call is stateless: no shipment or order is created.

Rates are sourced from each account's configured costing profile, or from the carrier's live rating API where enabled. Each returned rate carries the estimated cost, service name, and delivery promise for that account. Accounts that fail to price are omitted unless you set include_errors.

Compared with other pricing calls. Use this endpoint to compare carriers before creating a shipment, for example to pick the cheapest or fastest option across several accounts. It differs from two neighbours:

to re-price a shipment that already exists on its assigned carrier, use Estimate shipping cost, https://carriyo.com/docs/api/shipping/#estimate-shipping-cost-for-shipment.
for shopper-facing pricing at checkout, use the Storefront delivery options endpoint, https://carriyo.com/docs/api/storefront/#get-delivery-options, which supersedes this endpoint for that case.

Pricing detail. By default each rate returns a single estimated_shipping_cost amount. Request more detail with query parameters.

include_breakdown adds the line-by-line cost breakdown inside each rate's estimated_shipping_cost.
include_markup adds any configured markup to the returned rates.
include_errors adds per-carrier error_details for accounts that could not return a rate.

Query parameters

Name	Type	Required	Description
include_errors	boolean	No	Include per-carrier `error_details` for accounts that failed to return a rate.
include_breakdown	boolean	No	Include the line-by-line cost `breakdown` in each rate's `estimated_shipping_cost`.
include_markup	boolean	No	Include configured markup in the returned rates.

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: shipping-rates-requestrequired

merchantstring
ID of the merchant
entity_typestring
Values:FORWARDREVERSE
carrier_accountsshipping-rate-carrier-account-request[]required
List of carrier accounts for which shipping rate is requested.
paymentpayment-request
Payment details including the total value of the shipment and any pending Cash on Delivery amount.
customscustoms-object
Customs declaration details such as total declared value.
collectioncollection-object
Collection details chosen for the shipment, such as scheduled collection date.
deliverydelivery-object
Delivery details chosen for the shipment, such as chosen delivery type and scheduled delivery date.
pickuplocation-request | shipping-rate-location-requestrequired
Pickup address for the shipment. You can either pass a free-form address or a predefined location. For forward shipments, you must pass a predefined pickup location. Carriyo will copy the contact and address fields from the specified location. To specify the location, you can use Carriyo's internal location ID (partner_location_id), or your own location code (partner_location_code) as defined when you created the location in Carriyo. For reverse shipments, you can pass the customer's pickup address as a free-form pickup address.
dropoffshipping-rate-location-request | location-requestrequired
Dropoff address for the shipment. You can either pass a free-form address or a predefined location. For forward shipments, you can pass the customer's dropoff address as a free-form address. For reverse shipments, you must pass a predefined dropoff location. Carriyo will copy the contact and address fields from the specified location. To specify the location, you can use Carriyo's internal location ID (partner_location_id), or your own location code (partner_location_code) as defined when you created the location in Carriyo.
itemsshipping-rate-item-request[]
List of individual items or SKUs in a shipment.
parcelsshipping-rate-parcel-request[]required
(One of parcels or freight required) List of parcels in a B2C shipment.
freightobject
(One of parcels or freight required) List of packages of type pallet or carton in a B2B shipment.
custom_attributescustom-attributes
Custom attributes in the form of a map: {"attribute1" : ["value1", "value2"], "attribute2" : ["value1", "value2"]} Please Note: You can only use custom attributes if you are subscribed to this feature.

Responses

200Shipping rates from the requested carrier accounts for the prospective shipment.Schema: shipping-rates-response

shipping_ratesshipping-rate[]

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

get/carrier-accounts/{carrier-account-id}

Get carrier account

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Return a single carrier account by its carrier-account-id. By default the response matches a configured account (carrier-account-object). Pass statistics=true to receive activity timestamps (carrier-account-statistics-object).

Path parameters

Name	Type	Required	Description
carrier-account-id	string	Yes	Carrier account ID.

Query parameters

Name	Type	Required	Description
statistics	boolean	No	When `true`, the response includes carrier activity timestamps (last booking, last error, real-time and sync update dates).
integration_status	boolean	No	When `true`, the response includes `integration_statuses` with the result of live integration checks for the account.

Headers

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

Responses

200Returns the requested carrier account.

404Carrier account not found.

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

put/carrier-accounts/{carrier-account-id}

Update carrier account

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Replace the configuration of a carrier account. The request body fully replaces the existing account; fields you omit are reset to defaults.

Path parameters

Name	Type	Required	Description
carrier-account-id	string	Yes	Carrier account ID.

Headers

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

Request body

Content type: application/jsonSchema: carrier-account-request

carrier_account_idstring
Unique identifier of the carrier account.
parentobject
Parent account reference for child (e.g. Click-n-Ship) accounts.
merchantsstring[]
Merchant IDs allowed to use this account.
carrier_account_namestring
carrierstring
Carrier code (e.g. QUIQUP, DHL).
account_countrystring
ISO 3166-1 alpha-2 country code for the account.
account_currencystring
ISO 4217 currency code for the account.
daily_capacity_idstring
in_flight_capacity_idstring
costing_profile_idstring
network_idstring
propertyobject
Carrier-specific credential and configuration key-value pairs.
carrier_custom_attributesobject
document_mappingsobject
location_mappingsobject
Maps partner location IDs to carrier-specific location codes (hub codes, branch IDs, outlet codes, etc.).
labelobject
service_scheduleobject
Per-service pickup schedule configuration.
carrier_contact_emailstring
Contact email address for the carrier, stored on the account.
auto_ready_to_shipboolean
auto_schedule_pickupboolean
When true, a carrier pickup is scheduled automatically when a shipment is booked on this account, where the carrier supports pickup scheduling.
auto_return_confirmedboolean
auto_translate_to_englishboolean
use_carrier_costing_apiboolean
service_namestring
service_descriptionstring
delivery_promisestring
estimated_daysinteger
shipping_cost_markup_percentagenumberformat: double
statusstring
Values:ACTIVEINACTIVEDELETED
deletedboolean
Deprecated. Use status instead (DELETED).
generic_carrierboolean
packagingobject
unique_identifierstring
assetsobject

Responses

200Carrier account updated.Schema: carrier-account-object

carrier_account_idstring
Unique identifier of the carrier account.
parentobject
Parent account reference for child (e.g. Click-n-Ship) accounts.
merchantsstring[]
Merchant IDs allowed to use this account.
carrier_account_namestring
carrierstring
Carrier code (e.g. QUIQUP, DHL).
account_countrystring
ISO 3166-1 alpha-2 country code for the account.
account_currencystring
ISO 4217 currency code for the account.
daily_capacity_idstring
in_flight_capacity_idstring
costing_profile_idstring
network_idstring
propertyobject
Carrier-specific credential and configuration key-value pairs.
carrier_custom_attributesobject
document_mappingsobject
location_mappingsobject
Maps partner location IDs to carrier-specific location codes (hub codes, branch IDs, outlet codes, etc.).
labelobject
service_scheduleobject
Per-service pickup schedule configuration.
carrier_contact_emailstring
Contact email address for the carrier, stored on the account.
auto_ready_to_shipboolean
auto_schedule_pickupboolean
When true, a carrier pickup is scheduled automatically when a shipment is booked on this account, where the carrier supports pickup scheduling.
auto_return_confirmedboolean
auto_translate_to_englishboolean
use_carrier_costing_apiboolean
service_namestring
service_descriptionstring
delivery_promisestring
estimated_daysinteger
shipping_cost_markup_percentagenumberformat: double
statusstring
Values:ACTIVEINACTIVEDELETED
deletedboolean
Deprecated. Use status instead (DELETED).
generic_carrierboolean
packagingobject
unique_identifierstring
assetsobject
creation_datestringformat: date-time
update_datestringformat: date-time
deletion_datestringformat: date-time
integration_statusesobject
Present when integration_status=true on GET. Maps capability name to integration check result.

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

delete/carrier-accounts/{carrier-account-id}

Delete carrier account

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Soft-delete the specified carrier account. The account moves to DELETED status and is no longer returned by List carrier accounts, whatever status you pass. Get carrier account still returns it. Active bookings on the account are not affected.

Rule references block the delete. A rule that references the account blocks it even when the rule's ruleset is INACTIVE. Remove the account from the rule, or delete the rule, then retry; deactivating the ruleset is not enough.

One reference is not enforced. A service-level rule that names the account only in carrier_accounts does not block the delete, and is left referencing the deleted account.

Path parameters

Name	Type	Required	Description
carrier-account-id	string	Yes	Carrier account ID.

Headers

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

Responses

200Carrier account deleted. Response body is empty.

400

The request was rejected. One of:

an automation rule lists the account in carrier_accounts.
a service-level rule lists the account in carrier_ids.

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

Shipping Rules

Carriyo lets merchants automate carrier selection using shipping rules. Rules are grouped into rule sets, which can be assigned to merchant / country combinations. For example, a merchant can define one set of rules for the United States and a different set for Canada.

Each rule has a set of conditions that assign an inbound shipment to a chosen carrier when the conditions match. Rules have a sequence (priority), and the first rule to match the shipment determines the carrier. Conditions are flexible: you can match on the pickup or dropoff location, the delivery type, parcel weight, dimensions, or any other attribute of the shipment, and you can also cap the number of shipments routed to a carrier.

12 operations · 0 objects

post/automation-rulesets

Create automation ruleset

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Create an automation ruleset. The ruleset is the container for the routing rules Carriyo evaluates at booking time to pick a carrier account for each shipment. You can optionally pass an initial set of rules on the request; rules can also be added later.

One active ruleset per scope. Two ACTIVE rulesets cannot cover the same merchant, country and entity type; _ANY overlaps every value. Create the ruleset as INACTIVE when an ACTIVE one already covers its scope.

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: automation-ruleset-with-rules-request

automation_rulesetruleset-requestrequired
automation_rulesautomation-rule-request[]

Responses

201Automation ruleset and rules created.Schema: automation-ruleset-with-rules-response

automation_rulesetruleset-responserequired
automation_rulesautomation-rule-response[]

400

The request was rejected. One of:

the ruleset is ACTIVE and its merchants, countries and entity_type overlap another ACTIVE ruleset.
entity_type or status is missing, or merchants or countries is empty.
a rule in automation_rules has no carrier_accounts, or a merchant condition that lists no merchants.

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

get/automation-rulesets

List automation rulesets

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

List automation rulesets. Pass merchant to filter to one merchant, or omit it to return rulesets across all merchants. Pass entity-type (FORWARD or REVERSE) to narrow to forward-shipment or reverse-shipment rulesets.

Query parameters

Name	Type	Required	Description
merchant	string	No	Merchant ID to filter by.
entity-type	string	No	Shipment entity type to filter by.

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 automation rulesets.

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

tenantstring
rule_set_idstring
namestring
entity_typestring
Shipment direction the ruleset applies to. FORWARD for outbound shipments, REVERSE for returns.
Values:FORWARDREVERSE
merchantsstring[]
List of Merchant ids used in Ruleset. Use ["_ANY"] for all merchants
countriesstring[]
List of country iso2 codes used in Ruleset. Use ["_ANY"] for all countries
statusstring
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
update_datestringformat: date-time

400entity-type is not FORWARD or REVERSE.

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

get/automation-rulesets/{automation-ruleset-id}

Get automation ruleset

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Return a single automation ruleset by its automation-ruleset-id.

Path parameters

Name	Type	Required	Description
automation-ruleset-id	string	Yes	Automation ruleset ID.

Headers

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

Responses

200Returns the requested automation ruleset.Schema: ruleset-response

tenantstring
rule_set_idstring
namestring
entity_typestring
Shipment direction the ruleset applies to. FORWARD for outbound shipments, REVERSE for returns.
Values:FORWARDREVERSE
merchantsstring[]
List of Merchant ids used in Ruleset. Use ["_ANY"] for all merchants
countriesstring[]
List of country iso2 codes used in Ruleset. Use ["_ANY"] for all countries
statusstring
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
update_datestringformat: date-time

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

put/automation-rulesets/{automation-ruleset-id}

Replace automation ruleset

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Replace the ruleset and the rules it contains. The request body overwrites both; any rule not in the request is removed. To change just the ruleset's own metadata (name, merchants, entity type) without touching its rules, use PATCH instead.

Path parameters

Name	Type	Required	Description
automation-ruleset-id	string	Yes	Automation ruleset ID.

Headers

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

Request body

Content type: application/jsonSchema: automation-ruleset-with-rules-request

automation_rulesetruleset-requestrequired
automation_rulesautomation-rule-request[]

Responses

200Automation ruleset and rules updated.Schema: automation-ruleset-with-rules-response

automation_rulesetruleset-responserequired
automation_rulesautomation-rule-response[]

400

The request was rejected. One of:

the ruleset is ACTIVE and its merchants, countries and entity_type overlap another ACTIVE ruleset.
entity_type or status is missing, or merchants or countries is empty.
a rule in automation_rules has no carrier_accounts, or a merchant condition that lists no merchants.

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

patch/automation-rulesets/{automation-ruleset-id}

Update automation ruleset

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Update the ruleset's own metadata (name, merchants, entity type) without touching the rules it contains. To replace the rules as well, use PUT.

What to send. The whole ruleset, not only the fields you are changing: name, entity_type, merchants, countries and status are all required.

Path parameters

Name	Type	Required	Description
automation-ruleset-id	string	Yes	Automation ruleset ID.

Headers

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

Request body

Content type: application/jsonSchema: ruleset-request

namestringrequired
entity_typestringrequired
Shipment direction the ruleset applies to. FORWARD for outbound shipments, REVERSE for returns.
Values:FORWARDREVERSE
merchantsstring[]required
List of Merchant ids used in Ruleset. Use ["_ANY"] for all merchants
countriesstring[]required
List of country iso2 codes used in Ruleset. Use ["_ANY"] for all countries
statusstringrequired
Values:ACTIVEINACTIVEDELETED

Responses

200Automation ruleset updated. The response echoes the ruleset as sent, with rule_set_id, creation_date and update_date set to null.Schema: ruleset-response

tenantstring
rule_set_idstring
namestring
entity_typestring
Shipment direction the ruleset applies to. FORWARD for outbound shipments, REVERSE for returns.
Values:FORWARDREVERSE
merchantsstring[]
List of Merchant ids used in Ruleset. Use ["_ANY"] for all merchants
countriesstring[]
List of country iso2 codes used in Ruleset. Use ["_ANY"] for all countries
statusstring
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
update_datestringformat: date-time

400

The request was rejected. One of:

entity_type or status is missing, or merchants or countries is empty.
the ruleset is ACTIVE and its merchants, countries and entity_type overlap another ACTIVE ruleset.

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

delete/automation-rulesets/{automation-ruleset-id}

Delete automation ruleset

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Delete the ruleset and every rule it contains. Active bookings are unaffected, but from this point forward new bookings will fall through to any remaining rulesets, or return an error if no other ruleset matches.

Path parameters

Name	Type	Required	Description
automation-ruleset-id	string	Yes	Automation ruleset ID.

Headers

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

Responses

200Automation ruleset deleted.

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

post/automation-rulesets/{automation-ruleset-id}/rules

Create automation rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Add a new rule to an existing ruleset. The rule's position in the evaluation order is managed separately via Update automation sequence.

Path parameters

Name	Type	Required	Description
automation-ruleset-id	string	Yes	Automation ruleset ID.

Headers

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

Request body

Content type: application/jsonSchema: automation-rule-request

rule_idstring
Server-assigned rule identifier. Provide on update; omit on create.
rule_set_idstring
ID of the parent automation ruleset.
rule_namestring
Human-readable name for the rule.
descriptionstring
Optional notes about the rule.
sequenceinteger
Rule evaluation order within the ruleset. Lower values evaluate first.
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
merchantstring-condition-fieldrequired
Match shipment.merchant. value lists merchant IDs, or ["_ANY"] for all merchants, and is never empty.
creation_source_typestring-condition-field
Match shipment.creation_source.source_type.
update_source_typestring-condition-field
Match shipment.update_source.source_type.
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
payment_typestring-condition-field
Match shipment.payment.type.
delivery_typestring-condition-field
Match shipment.delivery_type.
order_typestring-condition-field
Match shipment.order_type.
delivery_optionstring-condition-field
Match the delivery option selected for the shipment.
dangerous_goodsstring
Filter on shipment.items[].dangerous_goods. Values: ANY, ONLY, NONE.
customer_address_verifiedstring
Filter on shipment.dropoff.address_verified. Values: ANY, VERIFIED, UNVERIFIED.
volumetric_weightnumber-area-condition-field
Match shipment parcels volumetric weight.
gross_weightnumber-area-condition-field
Match shipment parcels gross weight.
chargeable_weightnumber-area-condition-field
Match shipment parcels chargeable weight.
parcel_countnumber-area-condition-field
Match shipment parcel count.
order_valuenumber-area-condition-field
Match shipment.payment.total_amount.
item_valuenumber-area-condition-field
Match shipment.items[].price aggregated value.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is AND-combined.
scheduleschedule-dto
When the rule applies: recurring working_days / working_hours, optional working_period, blackout_days, and schedule_by (reference date). Omitted or empty working_days = always.
carrier_accountscarrier-account-bean[]required
Carrier accounts the rule selects from (CarrierAccountBean).
carrier_choicestring
Flat enum (CarrierChoice), not an object. CHEAPEST_CARRIER selects the lowest-cost account; ROUND_ROBIN uses round_robin_carriers quotas.
Values:CHEAPEST_CARRIERROUND_ROBIN
round_robin_carriersround-robin-carrier[]
Quota entries when carrier_choice is ROUND_ROBIN.
daily_limitdaily-limit
Optional per-rule daily cap.

Responses

201Automation rules created.Schema: automation-rule-response

rule_idstring
Server-assigned rule identifier. Provide on update; omit on create.
rule_set_idstring
ID of the parent automation ruleset.
rule_namestring
Human-readable name for the rule.
descriptionstring
Optional notes about the rule.
sequenceinteger
Rule evaluation order within the ruleset. Lower values evaluate first.
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
merchantstring-condition-field
Match shipment.merchant. value lists merchant IDs, or ["_ANY"] for all merchants, and is never empty.
creation_source_typestring-condition-field
Match shipment.creation_source.source_type.
update_source_typestring-condition-field
Match shipment.update_source.source_type.
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
payment_typestring-condition-field
Match shipment.payment.type.
delivery_typestring-condition-field
Match shipment.delivery_type.
order_typestring-condition-field
Match shipment.order_type.
delivery_optionstring-condition-field
Match the delivery option selected for the shipment.
dangerous_goodsstring
Filter on shipment.items[].dangerous_goods. Values: ANY, ONLY, NONE.
customer_address_verifiedstring
Filter on shipment.dropoff.address_verified. Values: ANY, VERIFIED, UNVERIFIED.
volumetric_weightnumber-area-condition-field
Match shipment parcels volumetric weight.
gross_weightnumber-area-condition-field
Match shipment parcels gross weight.
chargeable_weightnumber-area-condition-field
Match shipment parcels chargeable weight.
parcel_countnumber-area-condition-field
Match shipment parcel count.
order_valuenumber-area-condition-field
Match shipment.payment.total_amount.
item_valuenumber-area-condition-field
Match shipment.items[].price aggregated value.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is AND-combined.
scheduleschedule-dto
When the rule applies: recurring working_days / working_hours, optional working_period, blackout_days, and schedule_by (reference date). Omitted or empty working_days = always.
carrier_accountscarrier-account-bean[]
Carrier accounts the rule selects from (CarrierAccountBean).
carrier_choicestring
Flat enum (CarrierChoice), not an object. CHEAPEST_CARRIER selects the lowest-cost account; ROUND_ROBIN uses round_robin_carriers quotas.
Values:CHEAPEST_CARRIERROUND_ROBIN
round_robin_carriersround-robin-carrier[]
Quota entries when carrier_choice is ROUND_ROBIN.
daily_limitdaily-limit
Optional per-rule daily cap.
tenantstring
Tenant identifier.
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

400

The request was rejected. One of:

merchant is missing or lists no merchants, or carrier_accounts is empty.
another rule in the ruleset already uses this rule_name.

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

get/automation-rulesets/{automation-ruleset-id}/rules

List automation rules

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

List the rules in the specified ruleset. The list is not sorted; order the rules by sequence to get the evaluation order.

Path parameters

Name	Type	Required	Description
automation-ruleset-id	string	Yes	Automation ruleset ID.

Headers

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

Responses

200Matching automation rules.

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

rule_idstring
Server-assigned rule identifier. Provide on update; omit on create.
rule_set_idstring
ID of the parent automation ruleset.
rule_namestring
Human-readable name for the rule.
descriptionstring
Optional notes about the rule.
sequenceinteger
Rule evaluation order within the ruleset. Lower values evaluate first.
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
merchantstring-condition-field
Match shipment.merchant. value lists merchant IDs, or ["_ANY"] for all merchants, and is never empty.
creation_source_typestring-condition-field
Match shipment.creation_source.source_type.
update_source_typestring-condition-field
Match shipment.update_source.source_type.
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
payment_typestring-condition-field
Match shipment.payment.type.
delivery_typestring-condition-field
Match shipment.delivery_type.
order_typestring-condition-field
Match shipment.order_type.
delivery_optionstring-condition-field
Match the delivery option selected for the shipment.
dangerous_goodsstring
Filter on shipment.items[].dangerous_goods. Values: ANY, ONLY, NONE.
customer_address_verifiedstring
Filter on shipment.dropoff.address_verified. Values: ANY, VERIFIED, UNVERIFIED.
volumetric_weightnumber-area-condition-field
Match shipment parcels volumetric weight.
gross_weightnumber-area-condition-field
Match shipment parcels gross weight.
chargeable_weightnumber-area-condition-field
Match shipment parcels chargeable weight.
parcel_countnumber-area-condition-field
Match shipment parcel count.
order_valuenumber-area-condition-field
Match shipment.payment.total_amount.
item_valuenumber-area-condition-field
Match shipment.items[].price aggregated value.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is AND-combined.
scheduleschedule-dto
When the rule applies: recurring working_days / working_hours, optional working_period, blackout_days, and schedule_by (reference date). Omitted or empty working_days = always.
carrier_accountscarrier-account-bean[]
Carrier accounts the rule selects from (CarrierAccountBean).
carrier_choicestring
Flat enum (CarrierChoice), not an object. CHEAPEST_CARRIER selects the lowest-cost account; ROUND_ROBIN uses round_robin_carriers quotas.
Values:CHEAPEST_CARRIERROUND_ROBIN
round_robin_carriersround-robin-carrier[]
Quota entries when carrier_choice is ROUND_ROBIN.
daily_limitdaily-limit
Optional per-rule daily cap.
tenantstring
Tenant identifier.
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

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

patch/automation-rulesets/{ruleset-id}/rules/sequences

Update automation sequence

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Set the evaluation order of rules within the ruleset. Carriyo evaluates rules in this order at booking time and stops at the first matching rule, so sequence drives which rule wins when more than one would match the shipment.

Path parameters

Name	Type	Required	Description
ruleset-id	string	Yes	Automation ruleset ID.

Headers

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

Request body

Content type: application/jsonSchema: sequences-request

An array of sequences-request. Each item has the following fields:

rule_idstring
sequencenumber

Responses

200Automation rules sequence updated.Schema: sequences-request

An array of sequences-request. Each item has the following fields:

rule_idstring
sequencenumber

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

get/automation-rulesets/{ruleset-id}/rules/{automation-rule-id}

Get automation rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Return a single automation rule by its automation-rule-id within the ruleset.

Path parameters

Name	Type	Required	Description
ruleset-id	string	Yes	Automation ruleset ID.
automation-rule-id	string	Yes	Automation rule ID.

Headers

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

Responses

200Returns the requested automation rule.Schema: automation-rule-response

rule_idstring
Server-assigned rule identifier. Provide on update; omit on create.
rule_set_idstring
ID of the parent automation ruleset.
rule_namestring
Human-readable name for the rule.
descriptionstring
Optional notes about the rule.
sequenceinteger
Rule evaluation order within the ruleset. Lower values evaluate first.
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
merchantstring-condition-field
Match shipment.merchant. value lists merchant IDs, or ["_ANY"] for all merchants, and is never empty.
creation_source_typestring-condition-field
Match shipment.creation_source.source_type.
update_source_typestring-condition-field
Match shipment.update_source.source_type.
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
payment_typestring-condition-field
Match shipment.payment.type.
delivery_typestring-condition-field
Match shipment.delivery_type.
order_typestring-condition-field
Match shipment.order_type.
delivery_optionstring-condition-field
Match the delivery option selected for the shipment.
dangerous_goodsstring
Filter on shipment.items[].dangerous_goods. Values: ANY, ONLY, NONE.
customer_address_verifiedstring
Filter on shipment.dropoff.address_verified. Values: ANY, VERIFIED, UNVERIFIED.
volumetric_weightnumber-area-condition-field
Match shipment parcels volumetric weight.
gross_weightnumber-area-condition-field
Match shipment parcels gross weight.
chargeable_weightnumber-area-condition-field
Match shipment parcels chargeable weight.
parcel_countnumber-area-condition-field
Match shipment parcel count.
order_valuenumber-area-condition-field
Match shipment.payment.total_amount.
item_valuenumber-area-condition-field
Match shipment.items[].price aggregated value.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is AND-combined.
scheduleschedule-dto
When the rule applies: recurring working_days / working_hours, optional working_period, blackout_days, and schedule_by (reference date). Omitted or empty working_days = always.
carrier_accountscarrier-account-bean[]
Carrier accounts the rule selects from (CarrierAccountBean).
carrier_choicestring
Flat enum (CarrierChoice), not an object. CHEAPEST_CARRIER selects the lowest-cost account; ROUND_ROBIN uses round_robin_carriers quotas.
Values:CHEAPEST_CARRIERROUND_ROBIN
round_robin_carriersround-robin-carrier[]
Quota entries when carrier_choice is ROUND_ROBIN.
daily_limitdaily-limit
Optional per-rule daily cap.
tenantstring
Tenant identifier.
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

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

put/automation-rulesets/{ruleset-id}/rules/{automation-rule-id}

Update automation rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Replace the rule's configuration. The request body fully replaces the existing rule; fields you omit are reset to defaults. The rule's position in the evaluation sequence is unchanged and is managed separately via Update automation sequence.

Path parameters

Name	Type	Required	Description
ruleset-id	string	Yes	Automation ruleset ID.
automation-rule-id	string	Yes	Automation rule ID.

Headers

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

Request body

Content type: application/jsonSchema: automation-rule-request

rule_idstring
Server-assigned rule identifier. Provide on update; omit on create.
rule_set_idstring
ID of the parent automation ruleset.
rule_namestring
Human-readable name for the rule.
descriptionstring
Optional notes about the rule.
sequenceinteger
Rule evaluation order within the ruleset. Lower values evaluate first.
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
merchantstring-condition-fieldrequired
Match shipment.merchant. value lists merchant IDs, or ["_ANY"] for all merchants, and is never empty.
creation_source_typestring-condition-field
Match shipment.creation_source.source_type.
update_source_typestring-condition-field
Match shipment.update_source.source_type.
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
payment_typestring-condition-field
Match shipment.payment.type.
delivery_typestring-condition-field
Match shipment.delivery_type.
order_typestring-condition-field
Match shipment.order_type.
delivery_optionstring-condition-field
Match the delivery option selected for the shipment.
dangerous_goodsstring
Filter on shipment.items[].dangerous_goods. Values: ANY, ONLY, NONE.
customer_address_verifiedstring
Filter on shipment.dropoff.address_verified. Values: ANY, VERIFIED, UNVERIFIED.
volumetric_weightnumber-area-condition-field
Match shipment parcels volumetric weight.
gross_weightnumber-area-condition-field
Match shipment parcels gross weight.
chargeable_weightnumber-area-condition-field
Match shipment parcels chargeable weight.
parcel_countnumber-area-condition-field
Match shipment parcel count.
order_valuenumber-area-condition-field
Match shipment.payment.total_amount.
item_valuenumber-area-condition-field
Match shipment.items[].price aggregated value.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is AND-combined.
scheduleschedule-dto
When the rule applies: recurring working_days / working_hours, optional working_period, blackout_days, and schedule_by (reference date). Omitted or empty working_days = always.
carrier_accountscarrier-account-bean[]required
Carrier accounts the rule selects from (CarrierAccountBean).
carrier_choicestring
Flat enum (CarrierChoice), not an object. CHEAPEST_CARRIER selects the lowest-cost account; ROUND_ROBIN uses round_robin_carriers quotas.
Values:CHEAPEST_CARRIERROUND_ROBIN
round_robin_carriersround-robin-carrier[]
Quota entries when carrier_choice is ROUND_ROBIN.
daily_limitdaily-limit
Optional per-rule daily cap.

Responses

200Automation rule updated.Schema: automation-rule-response

rule_idstring
Server-assigned rule identifier. Provide on update; omit on create.
rule_set_idstring
ID of the parent automation ruleset.
rule_namestring
Human-readable name for the rule.
descriptionstring
Optional notes about the rule.
sequenceinteger
Rule evaluation order within the ruleset. Lower values evaluate first.
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
merchantstring-condition-field
Match shipment.merchant. value lists merchant IDs, or ["_ANY"] for all merchants, and is never empty.
creation_source_typestring-condition-field
Match shipment.creation_source.source_type.
update_source_typestring-condition-field
Match shipment.update_source.source_type.
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
payment_typestring-condition-field
Match shipment.payment.type.
delivery_typestring-condition-field
Match shipment.delivery_type.
order_typestring-condition-field
Match shipment.order_type.
delivery_optionstring-condition-field
Match the delivery option selected for the shipment.
dangerous_goodsstring
Filter on shipment.items[].dangerous_goods. Values: ANY, ONLY, NONE.
customer_address_verifiedstring
Filter on shipment.dropoff.address_verified. Values: ANY, VERIFIED, UNVERIFIED.
volumetric_weightnumber-area-condition-field
Match shipment parcels volumetric weight.
gross_weightnumber-area-condition-field
Match shipment parcels gross weight.
chargeable_weightnumber-area-condition-field
Match shipment parcels chargeable weight.
parcel_countnumber-area-condition-field
Match shipment parcel count.
order_valuenumber-area-condition-field
Match shipment.payment.total_amount.
item_valuenumber-area-condition-field
Match shipment.items[].price aggregated value.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is AND-combined.
scheduleschedule-dto
When the rule applies: recurring working_days / working_hours, optional working_period, blackout_days, and schedule_by (reference date). Omitted or empty working_days = always.
carrier_accountscarrier-account-bean[]
Carrier accounts the rule selects from (CarrierAccountBean).
carrier_choicestring
Flat enum (CarrierChoice), not an object. CHEAPEST_CARRIER selects the lowest-cost account; ROUND_ROBIN uses round_robin_carriers quotas.
Values:CHEAPEST_CARRIERROUND_ROBIN
round_robin_carriersround-robin-carrier[]
Quota entries when carrier_choice is ROUND_ROBIN.
daily_limitdaily-limit
Optional per-rule daily cap.
tenantstring
Tenant identifier.
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

400

The request was rejected. One of:

merchant is missing or lists no merchants, or carrier_accounts is empty.
another rule in the ruleset already uses this rule_name.

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

delete/automation-rulesets/{ruleset-id}/rules/{automation-rule-id}

Delete automation rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Remove a single rule from its ruleset. The rest of the ruleset is unchanged. New bookings that would have matched this rule fall through to the next matching rule in the ruleset.

Path parameters

Name	Type	Required	Description
ruleset-id	string	Yes	Automation ruleset ID.
automation-rule-id	string	Yes	Automation rule ID.

Headers

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

Responses

200Automation rule deleted.

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

Service Levels

A service level in Carriyo lets merchants define the expected timeline for a shipment. Service levels can be applied to each stage of the shipment journey: processing (preparing the shipment in the warehouse or store), collection (the carrier collecting the shipment), and delivery (the carrier delivering it once collected). You can also set up the customer promise: the end-to-end timeline from the moment the customer places the order.

Service levels work like shipping rules: they have a priority sequence and conditions, so you can define different expected timelines for different types of shipments.

12 operations · 0 objects

post/service-level-rulesets

Create service level ruleset

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Create a service-level ruleset. Service-level rules drive the delivery promise (estimated delivery date and any cut-off windows) Carriyo computes for each shipment. You can optionally include an initial set of rules on the request; rules can also be added later.

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: service-level-ruleset-with-rules-request

service_level_rulesetruleset-requestrequired
service_level_rulesservice-level-rule-request[]

Responses

201Service level ruleset and rules created.Schema: service-level-ruleset-with-rules-response

service_level_rulesetruleset-responserequired
service_level_rulesservice-level-rule-response[]

400

The request was rejected. One of:

the ruleset is ACTIVE and its merchants, countries and entity_type overlap another ACTIVE ruleset.
entity_type or status is missing, or merchants or countries is empty.
a rule in service_level_rules has no config_type or lead_sla, or a merchants condition that lists no merchants.

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

get/service-level-rulesets

List service level rulesets

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

List service-level rulesets. Pass merchant to filter to one merchant, or omit it to return rulesets across all merchants. Pass entity-type (FORWARD or REVERSE) to narrow to forward-shipment or reverse-shipment rulesets.

Query parameters

Name	Type	Required	Description
merchant	string	No	Merchant ID to filter by.
entity-type	string	No	Shipment entity type to filter by.

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 service level rulesets.

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

tenantstring
rule_set_idstring
namestring
entity_typestring
Shipment direction the ruleset applies to. FORWARD for outbound shipments, REVERSE for returns.
Values:FORWARDREVERSE
merchantsstring[]
List of Merchant ids used in Ruleset. Use ["_ANY"] for all merchants
countriesstring[]
List of country iso2 codes used in Ruleset. Use ["_ANY"] for all countries
statusstring
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
update_datestringformat: date-time

400entity-type is not FORWARD or REVERSE.

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

get/service-level-rulesets/{service-level-ruleset-id}

Get service level ruleset

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Return a single service-level ruleset by its service-level-ruleset-id.

Path parameters

Name	Type	Required	Description
service-level-ruleset-id	string	Yes	Service-level ruleset ID.

Headers

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

Responses

200Returns the requested service level ruleset.Schema: ruleset-response

tenantstring
rule_set_idstring
namestring
entity_typestring
Shipment direction the ruleset applies to. FORWARD for outbound shipments, REVERSE for returns.
Values:FORWARDREVERSE
merchantsstring[]
List of Merchant ids used in Ruleset. Use ["_ANY"] for all merchants
countriesstring[]
List of country iso2 codes used in Ruleset. Use ["_ANY"] for all countries
statusstring
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
update_datestringformat: date-time

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

put/service-level-rulesets/{service-level-ruleset-id}

Replace service level ruleset

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Replace the ruleset and the rules it contains. The request body overwrites both; any rule not in the request is removed. To change just the ruleset's own metadata without touching its rules, use PATCH instead.

Path parameters

Name	Type	Required	Description
service-level-ruleset-id	string	Yes	Service-level ruleset ID.

Headers

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

Request body

Content type: application/jsonSchema: service-level-ruleset-with-rules-request

service_level_rulesetruleset-requestrequired
service_level_rulesservice-level-rule-request[]

Responses

200Service level ruleset and rules updated.Schema: service-level-ruleset-with-rules-response

service_level_rulesetruleset-responserequired
service_level_rulesservice-level-rule-response[]

400

The request was rejected. One of:

the ruleset is ACTIVE and its merchants, countries and entity_type overlap another ACTIVE ruleset.
entity_type or status is missing, or merchants or countries is empty.
a rule in service_level_rules has no config_type or lead_sla, or a merchants condition that lists no merchants.

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

patch/service-level-rulesets/{service-level-ruleset-id}

Update service level ruleset

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Update the ruleset's own metadata (name, merchants, entity type) without touching the rules it contains. To replace the rules as well, use PUT.

What to send. The whole ruleset, not only the fields you are changing: name, entity_type, merchants, countries and status are all required.

Path parameters

Name	Type	Required	Description
service-level-ruleset-id	string	Yes	Service-level ruleset ID.

Headers

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

Request body

Content type: application/jsonSchema: ruleset-request

namestringrequired
entity_typestringrequired
Shipment direction the ruleset applies to. FORWARD for outbound shipments, REVERSE for returns.
Values:FORWARDREVERSE
merchantsstring[]required
List of Merchant ids used in Ruleset. Use ["_ANY"] for all merchants
countriesstring[]required
List of country iso2 codes used in Ruleset. Use ["_ANY"] for all countries
statusstringrequired
Values:ACTIVEINACTIVEDELETED

Responses

200Service level ruleset updated. The response echoes the ruleset as sent, without rule_set_id, creation_date or update_date.Schema: ruleset-response

tenantstring
rule_set_idstring
namestring
entity_typestring
Shipment direction the ruleset applies to. FORWARD for outbound shipments, REVERSE for returns.
Values:FORWARDREVERSE
merchantsstring[]
List of Merchant ids used in Ruleset. Use ["_ANY"] for all merchants
countriesstring[]
List of country iso2 codes used in Ruleset. Use ["_ANY"] for all countries
statusstring
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
update_datestringformat: date-time

400

The request was rejected. One of:

entity_type or status is missing, or merchants or countries is empty.
the ruleset is ACTIVE and its merchants, countries and entity_type overlap another ACTIVE ruleset.

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

delete/service-level-rulesets/{service-level-ruleset-id}

Delete service level ruleset

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Delete the ruleset and every rule it contains. Without an applicable service-level ruleset, Carriyo falls back to carrier-provided estimates for new shipments.

Path parameters

Name	Type	Required	Description
service-level-ruleset-id	string	Yes	Service-level ruleset ID.

Headers

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

Responses

200Service level ruleset deleted.

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

post/service-level-rulesets/{service-level-ruleset-id}/rules

Create service level rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Add a new rule to an existing service-level ruleset. The rule's position in the evaluation order is managed separately via Update service level sequence.

Path parameters

Name	Type	Required	Description
service-level-ruleset-id	string	Yes	Service-level ruleset ID.

Headers

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

Request body

Content type: application/jsonSchema: service-level-rule-request

rule_idstring
Server-assigned rule identifier. Provide on update; omit on create.
rule_set_idstring
ID of the parent service-level ruleset.
namestringrequired
Human-readable name for the rule.
descriptionstring
Optional notes about the rule.
sequenceintegerrequired
Rule evaluation order within the ruleset. Lower values evaluate first.
config_typestringrequired
SLA stage the rule applies to (ConfigType): fulfillment processing, shipping/collection, delivery attempt, or customer promise.
Values:FULFILLMENTSHIPPINGDELIVERYPROMISED
statusstringrequired
Rule status.
Values:ACTIVEINACTIVEDELETED
merchantsstring-condition-field
Match shipment.merchant (StringCondition with operator and value). value lists merchant IDs, or ["_ANY"] for all merchants, and is never empty.
creation_source_typestring-condition-field
Match shipment.creation_source.source_type.
update_source_typestring-condition-field
Match shipment.update_source.source_type.
delivery_typesstring-condition-field
Match shipment.delivery_type.
order_typesstring-condition-field
Match shipment.order_type.
carrier_idsstring-condition-field
Match carrier account IDs (carrier_id on assigned accounts).
carrier_accountsstring-condition-field
Match carrier account IDs.
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
volumetric_weightnumber-area-condition-field
Match shipment parcels volumetric weight.
gross_weightnumber-area-condition-field
Match shipment parcels gross weight.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is AND-combined.
scheduleschedule-dto
When the rule applies. Same shape as automation rule schedule. Omitted = always.
lead_slaestimation-slarequired
Lead-time SLA (EstimationSLA) — TIME_BASED or DAY_BASED.

Responses

201Service level rules created.Schema: service-level-rule-response

rule_idstring
Server-assigned rule identifier. Provide on update; omit on create.
rule_set_idstring
ID of the parent service-level ruleset.
namestring
Human-readable name for the rule.
descriptionstring
Optional notes about the rule.
sequenceinteger
Rule evaluation order within the ruleset. Lower values evaluate first.
config_typestring
SLA stage the rule applies to (ConfigType): fulfillment processing, shipping/collection, delivery attempt, or customer promise.
Values:FULFILLMENTSHIPPINGDELIVERYPROMISED
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
merchantsstring-condition-field
Match shipment.merchant (StringCondition with operator and value). value lists merchant IDs, or ["_ANY"] for all merchants, and is never empty.
creation_source_typestring-condition-field
Match shipment.creation_source.source_type.
update_source_typestring-condition-field
Match shipment.update_source.source_type.
delivery_typesstring-condition-field
Match shipment.delivery_type.
order_typesstring-condition-field
Match shipment.order_type.
carrier_idsstring-condition-field
Match carrier account IDs (carrier_id on assigned accounts).
carrier_accountsstring-condition-field
Match carrier account IDs.
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
volumetric_weightnumber-area-condition-field
Match shipment parcels volumetric weight.
gross_weightnumber-area-condition-field
Match shipment parcels gross weight.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is AND-combined.
scheduleschedule-dto
When the rule applies. Same shape as automation rule schedule. Omitted = always.
lead_slaestimation-sla
Lead-time SLA (EstimationSLA) — TIME_BASED or DAY_BASED.

400

The request was rejected. One of:

config_type or lead_sla is missing, or a DAY_BASED lead_sla has no eta_time.
a merchants condition lists no merchants.
another rule in the ruleset already uses this name.

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

get/service-level-rulesets/{service-level-ruleset-id}/rules

List service level rules

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

List the rules in the specified service-level ruleset. The list is not sorted; order the rules by sequence to get the evaluation order.

Path parameters

Name	Type	Required	Description
service-level-ruleset-id	string	Yes	Service-level ruleset ID.

Headers

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

Responses

200Matching service level rules.

An array of service-level-rule-response. Each item has the following fields:

rule_idstring
Server-assigned rule identifier. Provide on update; omit on create.
rule_set_idstring
ID of the parent service-level ruleset.
namestring
Human-readable name for the rule.
descriptionstring
Optional notes about the rule.
sequenceinteger
Rule evaluation order within the ruleset. Lower values evaluate first.
config_typestring
SLA stage the rule applies to (ConfigType): fulfillment processing, shipping/collection, delivery attempt, or customer promise.
Values:FULFILLMENTSHIPPINGDELIVERYPROMISED
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
merchantsstring-condition-field
Match shipment.merchant (StringCondition with operator and value). value lists merchant IDs, or ["_ANY"] for all merchants, and is never empty.
creation_source_typestring-condition-field
Match shipment.creation_source.source_type.
update_source_typestring-condition-field
Match shipment.update_source.source_type.
delivery_typesstring-condition-field
Match shipment.delivery_type.
order_typesstring-condition-field
Match shipment.order_type.
carrier_idsstring-condition-field
Match carrier account IDs (carrier_id on assigned accounts).
carrier_accountsstring-condition-field
Match carrier account IDs.
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
volumetric_weightnumber-area-condition-field
Match shipment parcels volumetric weight.
gross_weightnumber-area-condition-field
Match shipment parcels gross weight.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is AND-combined.
scheduleschedule-dto
When the rule applies. Same shape as automation rule schedule. Omitted = always.
lead_slaestimation-sla
Lead-time SLA (EstimationSLA) — TIME_BASED or DAY_BASED.

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

patch/service-level-rulesets/{ruleset-id}/rules/sequences

Update service level sequence

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Set the evaluation order of rules within the service-level ruleset. Carriyo evaluates rules in this order and stops at the first matching rule, so sequence drives which rule wins when more than one would match the shipment.

Path parameters

Name	Type	Required	Description
ruleset-id	string	Yes	Service-level ruleset ID.

Headers

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

Request body

Content type: application/jsonSchema: sequences-request

An array of sequences-request. Each item has the following fields:

rule_idstring
sequencenumber

Responses

200Service level rules sequence updated.Schema: sequences-request

An array of sequences-request. Each item has the following fields:

rule_idstring
sequencenumber

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

get/service-level-rulesets/{ruleset-id}/rules/{service-level-rule-id}

Get service level rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Return a single service-level rule by its service-level-rule-id within the ruleset.

Path parameters

Name	Type	Required	Description
ruleset-id	string	Yes	Service-level ruleset ID.
service-level-rule-id	string	Yes	Service-level rule ID.

Headers

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

Responses

200Returns the requested service level rule.Schema: service-level-rule-response

rule_idstring
Server-assigned rule identifier. Provide on update; omit on create.
rule_set_idstring
ID of the parent service-level ruleset.
namestring
Human-readable name for the rule.
descriptionstring
Optional notes about the rule.
sequenceinteger
Rule evaluation order within the ruleset. Lower values evaluate first.
config_typestring
SLA stage the rule applies to (ConfigType): fulfillment processing, shipping/collection, delivery attempt, or customer promise.
Values:FULFILLMENTSHIPPINGDELIVERYPROMISED
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
merchantsstring-condition-field
Match shipment.merchant (StringCondition with operator and value). value lists merchant IDs, or ["_ANY"] for all merchants, and is never empty.
creation_source_typestring-condition-field
Match shipment.creation_source.source_type.
update_source_typestring-condition-field
Match shipment.update_source.source_type.
delivery_typesstring-condition-field
Match shipment.delivery_type.
order_typesstring-condition-field
Match shipment.order_type.
carrier_idsstring-condition-field
Match carrier account IDs (carrier_id on assigned accounts).
carrier_accountsstring-condition-field
Match carrier account IDs.
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
volumetric_weightnumber-area-condition-field
Match shipment parcels volumetric weight.
gross_weightnumber-area-condition-field
Match shipment parcels gross weight.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is AND-combined.
scheduleschedule-dto
When the rule applies. Same shape as automation rule schedule. Omitted = always.
lead_slaestimation-sla
Lead-time SLA (EstimationSLA) — TIME_BASED or DAY_BASED.

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

put/service-level-rulesets/{ruleset-id}/rules/{service-level-rule-id}

Update service level rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Replace the rule's configuration. The request body fully replaces the existing rule; fields you omit are reset to defaults. The rule's position in the evaluation sequence is unchanged.

Path parameters

Name	Type	Required	Description
ruleset-id	string	Yes	Service-level ruleset ID.
service-level-rule-id	string	Yes	Service-level rule ID.

Headers

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

Request body

Content type: application/jsonSchema: service-level-rule-request

rule_idstring
Server-assigned rule identifier. Provide on update; omit on create.
rule_set_idstring
ID of the parent service-level ruleset.
namestringrequired
Human-readable name for the rule.
descriptionstring
Optional notes about the rule.
sequenceintegerrequired
Rule evaluation order within the ruleset. Lower values evaluate first.
config_typestringrequired
SLA stage the rule applies to (ConfigType): fulfillment processing, shipping/collection, delivery attempt, or customer promise.
Values:FULFILLMENTSHIPPINGDELIVERYPROMISED
statusstringrequired
Rule status.
Values:ACTIVEINACTIVEDELETED
merchantsstring-condition-field
Match shipment.merchant (StringCondition with operator and value). value lists merchant IDs, or ["_ANY"] for all merchants, and is never empty.
creation_source_typestring-condition-field
Match shipment.creation_source.source_type.
update_source_typestring-condition-field
Match shipment.update_source.source_type.
delivery_typesstring-condition-field
Match shipment.delivery_type.
order_typesstring-condition-field
Match shipment.order_type.
carrier_idsstring-condition-field
Match carrier account IDs (carrier_id on assigned accounts).
carrier_accountsstring-condition-field
Match carrier account IDs.
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
volumetric_weightnumber-area-condition-field
Match shipment parcels volumetric weight.
gross_weightnumber-area-condition-field
Match shipment parcels gross weight.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is AND-combined.
scheduleschedule-dto
When the rule applies. Same shape as automation rule schedule. Omitted = always.
lead_slaestimation-slarequired
Lead-time SLA (EstimationSLA) — TIME_BASED or DAY_BASED.

Responses

200Service level rule updated.Schema: service-level-rule-response

rule_idstring
Server-assigned rule identifier. Provide on update; omit on create.
rule_set_idstring
ID of the parent service-level ruleset.
namestring
Human-readable name for the rule.
descriptionstring
Optional notes about the rule.
sequenceinteger
Rule evaluation order within the ruleset. Lower values evaluate first.
config_typestring
SLA stage the rule applies to (ConfigType): fulfillment processing, shipping/collection, delivery attempt, or customer promise.
Values:FULFILLMENTSHIPPINGDELIVERYPROMISED
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
merchantsstring-condition-field
Match shipment.merchant (StringCondition with operator and value). value lists merchant IDs, or ["_ANY"] for all merchants, and is never empty.
creation_source_typestring-condition-field
Match shipment.creation_source.source_type.
update_source_typestring-condition-field
Match shipment.update_source.source_type.
delivery_typesstring-condition-field
Match shipment.delivery_type.
order_typesstring-condition-field
Match shipment.order_type.
carrier_idsstring-condition-field
Match carrier account IDs (carrier_id on assigned accounts).
carrier_accountsstring-condition-field
Match carrier account IDs.
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
volumetric_weightnumber-area-condition-field
Match shipment parcels volumetric weight.
gross_weightnumber-area-condition-field
Match shipment parcels gross weight.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is AND-combined.
scheduleschedule-dto
When the rule applies. Same shape as automation rule schedule. Omitted = always.
lead_slaestimation-sla
Lead-time SLA (EstimationSLA) — TIME_BASED or DAY_BASED.

400

The request was rejected. One of:

config_type or lead_sla is missing, or a DAY_BASED lead_sla has no eta_time.
a merchants condition lists no merchants.
another rule in the ruleset already uses this name.

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

delete/service-level-rulesets/{ruleset-id}/rules/{service-level-rule-id}

Delete service level rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Remove a single rule from its service-level ruleset. The rest of the ruleset is unchanged.

Path parameters

Name	Type	Required	Description
ruleset-id	string	Yes	Service-level ruleset ID.
service-level-rule-id	string	Yes	Service-level rule ID.

Headers

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

Responses

200Service level rule deleted.

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

Carrier Networks

Carrier networks group carriers for routing decisions across geographic regions.

6 operations · 0 objects

post/networks

Create carrier network

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Create a new carrier network. A network groups carriers and their geographic or postcode coverage so it can be referenced as a condition in automation rules.

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: carrier-network-dtorequired

network_idstring
Carriyo-issued identifier for the network. Server-assigned on create.
tenantstring
Tenant identifier (set from the request tenant-id header).
namestringrequired
Human-readable name for the network.
network_v2country-states-v2[]
Country / state / city / area entries that define the geographic scope of the network.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
carrier_account_idsstring[]
Carrier account IDs assigned to this network.
statusstring
Network status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

Responses

200Carrier network created.Schema: carrier-network-dto

network_idstring
Carriyo-issued identifier for the network. Server-assigned on create.
tenantstring
Tenant identifier (set from the request tenant-id header).
namestringrequired
Human-readable name for the network.
network_v2country-states-v2[]
Country / state / city / area entries that define the geographic scope of the network.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
carrier_account_idsstring[]
Carrier account IDs assigned to this network.
statusstring
Network status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

400

The request was rejected. One of:

name is missing or empty.
another carrier network already uses this name.

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

get/networks

List carrier networks

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Return all carrier networks defined for the tenant.

Headers

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

Responses

200The carrier networks defined for the tenant.

An array of carrier-network-dto. Each item has the following fields:

network_idstring
Carriyo-issued identifier for the network. Server-assigned on create.
tenantstring
Tenant identifier (set from the request tenant-id header).
namestringrequired
Human-readable name for the network.
network_v2country-states-v2[]
Country / state / city / area entries that define the geographic scope of the network.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
carrier_account_idsstring[]
Carrier account IDs assigned to this network.
statusstring
Network status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

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

get/networks/{id}

Get carrier network

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Return a single carrier network by its id.

Path parameters

Name	Type	Required	Description
id	string	Yes	Carrier network identifier.

Headers

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

Responses

200Returns the requested carrier network.Schema: carrier-network-dto

network_idstring
Carriyo-issued identifier for the network. Server-assigned on create.
tenantstring
Tenant identifier (set from the request tenant-id header).
namestringrequired
Human-readable name for the network.
network_v2country-states-v2[]
Country / state / city / area entries that define the geographic scope of the network.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
carrier_account_idsstring[]
Carrier account IDs assigned to this network.
statusstring
Network status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

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

put/networks/{id}

Update carrier network

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Replace a carrier network's name and coverage.

What to send. The body fully replaces the stored coverage: network_v2, pickup_postcode and dropoff_postcode you omit are removed from the network.

Carrier accounts. This call does not change which carrier accounts belong to the network. Use Assign carriers to network for that.

Path parameters

Name	Type	Required	Description
id	string	Yes	Carrier network identifier.

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: carrier-network-dtorequired

network_idstring
Carriyo-issued identifier for the network. Server-assigned on create.
tenantstring
Tenant identifier (set from the request tenant-id header).
namestringrequired
Human-readable name for the network.
network_v2country-states-v2[]
Country / state / city / area entries that define the geographic scope of the network.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
carrier_account_idsstring[]
Carrier account IDs assigned to this network.
statusstring
Network status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

Responses

200Carrier network updated.Schema: carrier-network-dto

network_idstring
Carriyo-issued identifier for the network. Server-assigned on create.
tenantstring
Tenant identifier (set from the request tenant-id header).
namestringrequired
Human-readable name for the network.
network_v2country-states-v2[]
Country / state / city / area entries that define the geographic scope of the network.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
carrier_account_idsstring[]
Carrier account IDs assigned to this network.
statusstring
Network status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

400

The request was rejected. One of:

name is missing or empty.
another carrier network already uses this name.
no carrier network with this id exists.

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

delete/networks/{id}

Delete carrier network

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Permanently delete a carrier network. Carrier accounts assigned to the network are unassigned from it and keep all their other settings.

Path parameters

Name	Type	Required	Description
id	string	Yes	Carrier network identifier.

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

200Carrier network deleted. Response body is empty.

400No carrier network with this id exists.

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

post/networks/{id}/assign

Assign carriers to network

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Replace the list of carrier accounts associated with the network. The request body is the full set; accounts not in the list are removed from the network.

Path parameters

Name	Type	Required	Description
id	string	Yes	Carrier network identifier.

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/jsonrequired

Responses

200Assignment saved. Returns the network with its carrier_account_ids.Schema: carrier-network-dto

network_idstring
Carriyo-issued identifier for the network. Server-assigned on create.
tenantstring
Tenant identifier (set from the request tenant-id header).
namestringrequired
Human-readable name for the network.
network_v2country-states-v2[]
Country / state / city / area entries that define the geographic scope of the network.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
carrier_account_idsstring[]
Carrier account IDs assigned to this network.
statusstring
Network status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

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

Carrier Costing

Costing profiles and rules define cost structures for carriers based on shipment characteristics.

13 operations · 0 objects

post/costing-rules

Create costing profile

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Create a shipment costing profile together with its rules.

What to send. costing_profile and costing_rules are both required. Send an empty costing_rules array to create a profile with no rules. profile_name must be unique within the tenant.

Known issue. A body with no costing_rules answers 500 after the profile has been created.

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: shipment-costing-dtorequired

costing_profileshipment-costing-profile-dtorequired
A shipment costing profile defines how carrier charges are computed for shipments routed through specific carrier accounts. The profile holds the default cost and breakdown; per-shipment rules can override the cost based on conditions.
costing_rulesshipment-costing-rule-dto[]required
Full rule set for the profile (replaces existing rules on PUT).

Responses

201Costing profile created, with its rules.Schema: shipment-costing-dto

costing_profileshipment-costing-profile-dtorequired
A shipment costing profile defines how carrier charges are computed for shipments routed through specific carrier accounts. The profile holds the default cost and breakdown; per-shipment rules can override the cost based on conditions.
costing_rulesshipment-costing-rule-dto[]required
Full rule set for the profile (replaces existing rules on PUT).

400

The request was rejected. One of:

profile_name, carrier_billing_currency, default_shipment_cost or tax_rate is missing.
another costing profile already uses this profile_name.

500The body had no costing_rules. The profile was created before the failure, so treat this as a completed write and do not retry it.

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

get/costing-rules

List costing profiles

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Return all shipment costing profiles configured for the tenant.

Headers

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

Responses

200The costing profiles configured for the tenant, without their rules.

An array of shipment-costing-profile-dto. Each item has the following fields:

profile_idstring
Carriyo-issued identifier for the costing profile. Server-assigned on create.
profile_namestringrequired
Human-readable name for the profile.
carrier_billing_currencystringrequired
ISO 4217 currency code in which the carrier bills (e.g. USD, AED, EUR).
default_shipment_costnumberrequired
Default per-shipment cost in carrier_billing_currency. Used when no rule matches.
tax_ratenumberrequired
Tax rate (percentage, e.g. 5.0 for 5%) applied on top of the computed cost.
breakdownbreakdown-item[]
Default cost breakdown lines (base fee, fuel surcharge, etc.).
carrier_account_idsstring[]
Carrier account IDs to which this profile applies.
statusstring
Profile status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

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

get/costing-rules/{id}

Get costing profile

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Return a single shipment costing profile by its id. The profile's rules are not included; read them with List costing rules.

Path parameters

Name	Type	Required	Description
id	string	Yes	Costing profile ID.

Headers

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

Responses

200Returns the requested costing profile, without its rules.Schema: shipment-costing-profile-dto

profile_idstring
Carriyo-issued identifier for the costing profile. Server-assigned on create.
profile_namestringrequired
Human-readable name for the profile.
carrier_billing_currencystringrequired
ISO 4217 currency code in which the carrier bills (e.g. USD, AED, EUR).
default_shipment_costnumberrequired
Default per-shipment cost in carrier_billing_currency. Used when no rule matches.
tax_ratenumberrequired
Tax rate (percentage, e.g. 5.0 for 5%) applied on top of the computed cost.
breakdownbreakdown-item[]
Default cost breakdown lines (base fee, fuel surcharge, etc.).
carrier_account_idsstring[]
Carrier account IDs to which this profile applies.
statusstring
Profile status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

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

put/costing-rules/{id}

Update costing profile

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Replace the costing profile and all of its rules.

What to send. costing_profile and the full costing_rules list. A rule sent with its rule_id is updated, a rule sent without one is added, and any existing rule left out of the list is deleted.

Known issue. Each existing rule updated by this call has its stored creation_date cleared.

Path parameters

Name	Type	Required	Description
id	string	Yes	Costing profile ID.

Headers

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

Request body

Content type: application/jsonSchema: shipment-costing-dtorequired

costing_profileshipment-costing-profile-dtorequired
A shipment costing profile defines how carrier charges are computed for shipments routed through specific carrier accounts. The profile holds the default cost and breakdown; per-shipment rules can override the cost based on conditions.
costing_rulesshipment-costing-rule-dto[]required
Full rule set for the profile (replaces existing rules on PUT).

Responses

200Costing profile and rules updated.Schema: shipment-costing-dto

costing_profileshipment-costing-profile-dtorequired
A shipment costing profile defines how carrier charges are computed for shipments routed through specific carrier accounts. The profile holds the default cost and breakdown; per-shipment rules can override the cost based on conditions.
costing_rulesshipment-costing-rule-dto[]required
Full rule set for the profile (replaces existing rules on PUT).

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

patch/costing-rules/{id}

Patch costing profile

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Update the costing profile's own fields without touching the rules it contains. To replace the rules as well, use PUT.

What to send. The whole profile, not only the fields you are changing: profile_name, carrier_billing_currency, default_shipment_cost and tax_rate are all required. Include the profile's profile_id in the body as well.

Known issue. A body without profile_id answers 500, but the change has already been saved. Do not retry on that 500.

Path parameters

Name	Type	Required	Description
id	string	Yes	Costing profile ID.

Headers

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

Request body

Content type: application/jsonSchema: shipment-costing-profile-dtorequired

profile_idstring
Carriyo-issued identifier for the costing profile. Server-assigned on create.
profile_namestringrequired
Human-readable name for the profile.
carrier_billing_currencystringrequired
ISO 4217 currency code in which the carrier bills (e.g. USD, AED, EUR).
default_shipment_costnumberrequired
Default per-shipment cost in carrier_billing_currency. Used when no rule matches.
tax_ratenumberrequired
Tax rate (percentage, e.g. 5.0 for 5%) applied on top of the computed cost.
breakdownbreakdown-item[]
Default cost breakdown lines (base fee, fuel surcharge, etc.).
carrier_account_idsstring[]
Carrier account IDs to which this profile applies.
statusstring
Profile status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

Responses

200Costing profile updated. The response echoes the profile as sent, with creation_date and update_date set to null.Schema: shipment-costing-profile-dto

profile_idstring
Carriyo-issued identifier for the costing profile. Server-assigned on create.
profile_namestringrequired
Human-readable name for the profile.
carrier_billing_currencystringrequired
ISO 4217 currency code in which the carrier bills (e.g. USD, AED, EUR).
default_shipment_costnumberrequired
Default per-shipment cost in carrier_billing_currency. Used when no rule matches.
tax_ratenumberrequired
Tax rate (percentage, e.g. 5.0 for 5%) applied on top of the computed cost.
breakdownbreakdown-item[]
Default cost breakdown lines (base fee, fuel surcharge, etc.).
carrier_account_idsstring[]
Carrier account IDs to which this profile applies.
statusstring
Profile status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

400

The request was rejected. One of:

profile_name, carrier_billing_currency, default_shipment_cost or tax_rate is missing.
another costing profile already uses this profile_name.
no costing profile with this id exists.

500The body had no profile_id. The change was saved before the failure, so treat this as a completed write and do not retry it.

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

delete/costing-rules/{id}

Delete costing profile

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Permanently delete a costing profile.

What happens. It depends on what the profile is attached to:

a profile with rules and no assigned carrier accounts is deleted together with its rules.
a profile with assigned carrier accounts and no rules is deleted, and the accounts are unassigned from it.
a profile with both is rejected.

Path parameters

Name	Type	Required	Description
id	string	Yes	Costing profile ID.

Headers

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

Responses

200Costing profile deleted. Response body is empty.

400

The request was rejected. One of:

the profile has rules and is also assigned to carrier accounts. Remove the rules or unassign the accounts first.
no costing profile with this id exists.

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

post/costing-rules/{id}/assign

Assign carrier accounts to costing profile

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Replace the list of carrier accounts that use the costing profile. The request body is the full set; accounts not in the list are unassigned, and an empty array unassigns every account.

Path parameters

Name	Type	Required	Description
id	string	Yes	Costing profile ID.

Headers

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

Request body

Content type: application/jsonrequired

Responses

200Assignment saved. Returns the costing profile with its carrier_account_ids.Schema: shipment-costing-profile-dto

profile_idstring
Carriyo-issued identifier for the costing profile. Server-assigned on create.
profile_namestringrequired
Human-readable name for the profile.
carrier_billing_currencystringrequired
ISO 4217 currency code in which the carrier bills (e.g. USD, AED, EUR).
default_shipment_costnumberrequired
Default per-shipment cost in carrier_billing_currency. Used when no rule matches.
tax_ratenumberrequired
Tax rate (percentage, e.g. 5.0 for 5%) applied on top of the computed cost.
breakdownbreakdown-item[]
Default cost breakdown lines (base fee, fuel surcharge, etc.).
carrier_account_idsstring[]
Carrier account IDs to which this profile applies.
statusstring
Profile status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

400No costing profile with this id exists.

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

post/costing-rules/{profile_id}/rules

Add costing rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Add a new costing rule to an existing shipment costing profile. The rule name must be unique within the profile, and cost_structure must set exactly one of fixed_cost and variable_cost.

Path parameters

Name	Type	Required	Description
profile_id	string	Yes	Costing profile ID.

Headers

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

Request body

Content type: application/jsonSchema: shipment-costing-rule-dtorequired

rule_idstring
Carriyo-issued rule identifier.
costing_profile_idstring
ID of the parent costing profile.
namestringrequired
Human-readable name for the rule.
entity_typestring
Shipment direction the rule applies to. SHIPMENT for outbound shipments, REVERSE_SHIPMENT for returns; rulesets name the same two directions FORWARD and REVERSE.
Values:SHIPMENTREVERSE_SHIPMENT
sequenceinteger
Rule evaluation order within the profile. Lower values evaluate first.
cost_structureshipment-cost-structurerequired
Per-rule cost model (ShipmentCostStructure) when the profile default does not apply.
cost_per_shipmentnumber
Per-shipment cost in the profile currency. Deprecated; use cost_structure instead, which wins when both are set.
effective_datestringformat: date-time
Date from which the rule is effective.
expiry_datestringformat: date-time
Date after which the rule no longer applies.
scheduleschedule-dto
Rule schedule (ScheduleDto). Used on automation rules, service-level rules, and costing rules. Empty or omitted working_days means the rule applies at any time.
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
delivery_typestring-condition-field
Match shipment delivery_type.
order_typestring-condition-field
Match shipment order_type.
payment_typestring-condition-field
Match shipment.payment.type.
dangerous_goodsstring
Filter on shipment.items[].dangerous_goods. Values: ANY, ONLY, NONE.
volumetric_weightnumber-area-condition-field
Match shipment parcels volumetric weight.
gross_weightnumber-area-condition-field
Match shipment parcels gross weight.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is AND-combined.
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

Responses

201Created.Schema: shipment-costing-rule-dto

rule_idstring
Carriyo-issued rule identifier.
costing_profile_idstring
ID of the parent costing profile.
namestringrequired
Human-readable name for the rule.
entity_typestring
Shipment direction the rule applies to. SHIPMENT for outbound shipments, REVERSE_SHIPMENT for returns; rulesets name the same two directions FORWARD and REVERSE.
Values:SHIPMENTREVERSE_SHIPMENT
sequenceinteger
Rule evaluation order within the profile. Lower values evaluate first.
cost_structureshipment-cost-structurerequired
Per-rule cost model (ShipmentCostStructure) when the profile default does not apply.
cost_per_shipmentnumber
Per-shipment cost in the profile currency. Deprecated; use cost_structure instead, which wins when both are set.
effective_datestringformat: date-time
Date from which the rule is effective.
expiry_datestringformat: date-time
Date after which the rule no longer applies.
scheduleschedule-dto
Rule schedule (ScheduleDto). Used on automation rules, service-level rules, and costing rules. Empty or omitted working_days means the rule applies at any time.
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
delivery_typestring-condition-field
Match shipment delivery_type.
order_typestring-condition-field
Match shipment order_type.
payment_typestring-condition-field
Match shipment.payment.type.
dangerous_goodsstring
Filter on shipment.items[].dangerous_goods. Values: ANY, ONLY, NONE.
volumetric_weightnumber-area-condition-field
Match shipment parcels volumetric weight.
gross_weightnumber-area-condition-field
Match shipment parcels gross weight.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is AND-combined.
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

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

get/costing-rules/{profile_id}/rules

List costing rules

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

List the costing rules in the specified costing profile. The list is not sorted; order the rules by sequence to get the evaluation order.

Path parameters

Name	Type	Required	Description
profile_id	string	Yes	Costing profile ID.

Headers

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

Responses

200The costing rules in the profile. Empty when the profile has no rules.

An array of shipment-costing-rule-dto. Each item has the following fields:

rule_idstring
Carriyo-issued rule identifier.
costing_profile_idstring
ID of the parent costing profile.
namestringrequired
Human-readable name for the rule.
entity_typestring
Shipment direction the rule applies to. SHIPMENT for outbound shipments, REVERSE_SHIPMENT for returns; rulesets name the same two directions FORWARD and REVERSE.
Values:SHIPMENTREVERSE_SHIPMENT
sequenceinteger
Rule evaluation order within the profile. Lower values evaluate first.
cost_structureshipment-cost-structurerequired
Per-rule cost model (ShipmentCostStructure) when the profile default does not apply.
cost_per_shipmentnumber
Per-shipment cost in the profile currency. Deprecated; use cost_structure instead, which wins when both are set.
effective_datestringformat: date-time
Date from which the rule is effective.
expiry_datestringformat: date-time
Date after which the rule no longer applies.
scheduleschedule-dto
Rule schedule (ScheduleDto). Used on automation rules, service-level rules, and costing rules. Empty or omitted working_days means the rule applies at any time.
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
delivery_typestring-condition-field
Match shipment delivery_type.
order_typestring-condition-field
Match shipment order_type.
payment_typestring-condition-field
Match shipment.payment.type.
dangerous_goodsstring
Filter on shipment.items[].dangerous_goods. Values: ANY, ONLY, NONE.
volumetric_weightnumber-area-condition-field
Match shipment parcels volumetric weight.
gross_weightnumber-area-condition-field
Match shipment parcels gross weight.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is AND-combined.
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

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

patch/costing-rules/{profile_id}/rules/sequences

Update costing rules sequence

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Set the evaluation order of the costing rules in a profile. Rules with a lower sequence are evaluated first.

What to send. One entry per rule to reorder, with its rule_id and its new sequence. Rules you leave out keep their sequence. An entry whose rule_id is not in the profile is ignored.

Path parameters

Name	Type	Required	Description
profile_id	string	Yes	Costing profile ID.

Headers

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

Request body

Content type: application/jsonSchema: sequences-requestrequired

An array of sequences-request. Each item has the following fields:

rule_idstring
sequencenumber

Responses

200Sequences saved. The response echoes the request body.Schema: sequences-request

An array of sequences-request. Each item has the following fields:

rule_idstring
sequencenumber

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

get/costing-rules/{profile_id}/rules/{rule_id}

Get costing rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Return a single costing rule from the specified profile.

Path parameters

Name	Type	Required	Description
profile_id	string	Yes	Costing profile ID.
rule_id	string	Yes	Costing rule ID, the rule's `rule_id`.

Headers

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

Responses

200Returns the requested costing rule.Schema: shipment-costing-rule-dto

rule_idstring
Carriyo-issued rule identifier.
costing_profile_idstring
ID of the parent costing profile.
namestringrequired
Human-readable name for the rule.
entity_typestring
Shipment direction the rule applies to. SHIPMENT for outbound shipments, REVERSE_SHIPMENT for returns; rulesets name the same two directions FORWARD and REVERSE.
Values:SHIPMENTREVERSE_SHIPMENT
sequenceinteger
Rule evaluation order within the profile. Lower values evaluate first.
cost_structureshipment-cost-structurerequired
Per-rule cost model (ShipmentCostStructure) when the profile default does not apply.
cost_per_shipmentnumber
Per-shipment cost in the profile currency. Deprecated; use cost_structure instead, which wins when both are set.
effective_datestringformat: date-time
Date from which the rule is effective.
expiry_datestringformat: date-time
Date after which the rule no longer applies.
scheduleschedule-dto
Rule schedule (ScheduleDto). Used on automation rules, service-level rules, and costing rules. Empty or omitted working_days means the rule applies at any time.
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
delivery_typestring-condition-field
Match shipment delivery_type.
order_typestring-condition-field
Match shipment order_type.
payment_typestring-condition-field
Match shipment.payment.type.
dangerous_goodsstring
Filter on shipment.items[].dangerous_goods. Values: ANY, ONLY, NONE.
volumetric_weightnumber-area-condition-field
Match shipment parcels volumetric weight.
gross_weightnumber-area-condition-field
Match shipment parcels gross weight.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is AND-combined.
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

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

put/costing-rules/{profile_id}/rules/{rule_id}

Update costing rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Replace a costing rule.

Known issue. Every successful call clears the rule's stored creation_date, and it cannot be restored through the API. The call still answers 200, so the loss is only visible when you read the rule back.

What to send. The body fully replaces the stored rule: conditions you omit are removed from the rule. cost_structure must set exactly one of fixed_cost and variable_cost.

Path parameters

Name	Type	Required	Description
profile_id	string	Yes	Costing profile ID.
rule_id	string	Yes	Costing rule ID, the rule's `rule_id`.

Headers

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

Request body

Content type: application/jsonSchema: shipment-costing-rule-dtorequired

rule_idstring
Carriyo-issued rule identifier.
costing_profile_idstring
ID of the parent costing profile.
namestringrequired
Human-readable name for the rule.
entity_typestring
Shipment direction the rule applies to. SHIPMENT for outbound shipments, REVERSE_SHIPMENT for returns; rulesets name the same two directions FORWARD and REVERSE.
Values:SHIPMENTREVERSE_SHIPMENT
sequenceinteger
Rule evaluation order within the profile. Lower values evaluate first.
cost_structureshipment-cost-structurerequired
Per-rule cost model (ShipmentCostStructure) when the profile default does not apply.
cost_per_shipmentnumber
Per-shipment cost in the profile currency. Deprecated; use cost_structure instead, which wins when both are set.
effective_datestringformat: date-time
Date from which the rule is effective.
expiry_datestringformat: date-time
Date after which the rule no longer applies.
scheduleschedule-dto
Rule schedule (ScheduleDto). Used on automation rules, service-level rules, and costing rules. Empty or omitted working_days means the rule applies at any time.
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
delivery_typestring-condition-field
Match shipment delivery_type.
order_typestring-condition-field
Match shipment order_type.
payment_typestring-condition-field
Match shipment.payment.type.
dangerous_goodsstring
Filter on shipment.items[].dangerous_goods. Values: ANY, ONLY, NONE.
volumetric_weightnumber-area-condition-field
Match shipment parcels volumetric weight.
gross_weightnumber-area-condition-field
Match shipment parcels gross weight.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is AND-combined.
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

Responses

200Costing rule updated, and its stored creation_date cleared. The response echoes the rule as sent, with rule_id, creation_date and update_date set to null.Schema: shipment-costing-rule-dto

rule_idstring
Carriyo-issued rule identifier.
costing_profile_idstring
ID of the parent costing profile.
namestringrequired
Human-readable name for the rule.
entity_typestring
Shipment direction the rule applies to. SHIPMENT for outbound shipments, REVERSE_SHIPMENT for returns; rulesets name the same two directions FORWARD and REVERSE.
Values:SHIPMENTREVERSE_SHIPMENT
sequenceinteger
Rule evaluation order within the profile. Lower values evaluate first.
cost_structureshipment-cost-structurerequired
Per-rule cost model (ShipmentCostStructure) when the profile default does not apply.
cost_per_shipmentnumber
Per-shipment cost in the profile currency. Deprecated; use cost_structure instead, which wins when both are set.
effective_datestringformat: date-time
Date from which the rule is effective.
expiry_datestringformat: date-time
Date after which the rule no longer applies.
scheduleschedule-dto
Rule schedule (ScheduleDto). Used on automation rules, service-level rules, and costing rules. Empty or omitted working_days means the rule applies at any time.
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
delivery_typestring-condition-field
Match shipment delivery_type.
order_typestring-condition-field
Match shipment order_type.
payment_typestring-condition-field
Match shipment.payment.type.
dangerous_goodsstring
Filter on shipment.items[].dangerous_goods. Values: ANY, ONLY, NONE.
volumetric_weightnumber-area-condition-field
Match shipment parcels volumetric weight.
gross_weightnumber-area-condition-field
Match shipment parcels gross weight.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is AND-combined.
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

400

The request was rejected. One of:

name or cost_structure is missing.
cost_structure sets both fixed_cost and variable_cost, or neither.
cost_structure.cod_surcharge sets both fixed_cost and percentage_cost, or neither.
another rule in the profile already uses this name.
a pickup or dropoff location condition is combined with a geography or postcode condition for the same side.
no rule with this rule_id exists in the profile.

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

delete/costing-rules/{profile_id}/rules/{rule_id}

Delete costing rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Permanently delete a costing rule from the profile. The remaining rules keep their sequence.

Path parameters

Name	Type	Required	Description
profile_id	string	Yes	Costing profile ID.
rule_id	string	Yes	Costing rule ID, the rule's `rule_id`.

Headers

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

Responses

200Costing rule deleted. Response body is empty.

400No rule with this rule_id exists in the profile.

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

Carrier Capacity

Capacity profiles define shipment-volume thresholds and constraints per carrier across regions and time windows.

13 operations · 0 objects

post/capacities

Create capacity profile

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Create a capacity profile. The profile holds a set of rules that cap the number of shipments Carriyo will book against the assigned carrier accounts within a time window, so capacity-constrained carriers don't get overwhelmed.

What to send. capacity_profile, and an empty capacity_rules array. profile_name must be unique within the tenant.

Known issue. A non-empty capacity_rules array answers 500 after the profile has been created without the rules. Create the profile first, then add each rule with Add capacity rule.

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: capacity-profile-requestrequired

capacity_profilecapacity-profile-dto
A capacity profile groups capacity rules and applies them to one or more carrier accounts. DAILY capacity caps shipments per UTC day; IN_FLIGHT capacity caps shipments currently in the carrier network.
capacity_rulescapacity-rule-dto[]

Responses

201Capacity profile created.Schema: capacity-profile-request

capacity_profilecapacity-profile-dto
A capacity profile groups capacity rules and applies them to one or more carrier accounts. DAILY capacity caps shipments per UTC day; IN_FLIGHT capacity caps shipments currently in the carrier network.
capacity_rulescapacity-rule-dto[]

400

The request was rejected. One of:

profile_name is missing or empty, or capacity_type is missing.
another capacity profile already uses this profile_name.

500capacity_rules was not empty. The profile was created without the rules before the failure, so do not retry the call; add the rules with Add capacity rule.

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

get/capacities

List capacity profiles

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Return all capacity profiles configured for the tenant.

Headers

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

Responses

200The capacity profiles configured for the tenant, without their rules.

An array of capacity-profile-dto. Each item has the following fields:

profile_idstring
Carriyo-issued identifier for the capacity profile. Server-assigned on create.
profile_namestringrequired
Human-readable name for the profile.
capacity_typestringrequired
Capacity-counting mode: DAILY resets at the configured daily start time; IN_FLIGHT counts shipments not yet delivered.
Values:DAILYIN_FLIGHT
daily_capacity_start_timestring
For DAILY profiles: HH:mm time at which the daily window resets (24-hour, UTC). Ignored for IN_FLIGHT.
carrier_account_idsstring[]
Carrier account IDs that this profile applies to.
statusstring
Profile status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

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

get/capacities/{id}

Get capacity profile

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Return a single capacity profile by its id. The profile's rules are not included; read them with List capacity rules.

Path parameters

Name	Type	Required	Description
id	string	Yes	Capacity profile ID.

Headers

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

Responses

200Returns the requested capacity profile, without its rules.Schema: capacity-profile-dto

profile_idstring
Carriyo-issued identifier for the capacity profile. Server-assigned on create.
profile_namestringrequired
Human-readable name for the profile.
capacity_typestringrequired
Capacity-counting mode: DAILY resets at the configured daily start time; IN_FLIGHT counts shipments not yet delivered.
Values:DAILYIN_FLIGHT
daily_capacity_start_timestring
For DAILY profiles: HH:mm time at which the daily window resets (24-hour, UTC). Ignored for IN_FLIGHT.
carrier_account_idsstring[]
Carrier account IDs that this profile applies to.
statusstring
Profile status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

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

put/capacities/{id}

Update capacity profile

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Replace the capacity profile and its rules.

What to send. capacity_profile and the full capacity_rules list. A rule sent with its capacity_id is updated, a rule sent without one is added, and any existing rule left out of the list is deleted.

Known issue. Every successful call clears the profile's stored creation_date.

Path parameters

Name	Type	Required	Description
id	string	Yes	Capacity profile ID.

Headers

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

Request body

Content type: application/jsonSchema: capacity-profile-requestrequired

capacity_profilecapacity-profile-dto
A capacity profile groups capacity rules and applies them to one or more carrier accounts. DAILY capacity caps shipments per UTC day; IN_FLIGHT capacity caps shipments currently in the carrier network.
capacity_rulescapacity-rule-dto[]

Responses

200Capacity profile and rules updated.Schema: capacity-profile-request

capacity_profilecapacity-profile-dto
A capacity profile groups capacity rules and applies them to one or more carrier accounts. DAILY capacity caps shipments per UTC day; IN_FLIGHT capacity caps shipments currently in the carrier network.
capacity_rulescapacity-rule-dto[]

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

patch/capacities/{id}

Patch capacity profile

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Update the capacity profile's own fields without touching the rules it contains. To replace the rules as well, use PUT.

What to send. The whole profile, not only the fields you are changing: profile_name and capacity_type are required. Include the profile's profile_id in the body as well.

Known issues. Every successful call clears the profile's stored creation_date, and it cannot be restored through the API. A body without profile_id answers 500, but the change has already been saved and creation_date already cleared. Do not retry on that 500.

Path parameters

Name	Type	Required	Description
id	string	Yes	Capacity profile ID.

Headers

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

Request body

Content type: application/jsonSchema: capacity-profile-dtorequired

profile_idstring
Carriyo-issued identifier for the capacity profile. Server-assigned on create.
profile_namestringrequired
Human-readable name for the profile.
capacity_typestringrequired
Capacity-counting mode: DAILY resets at the configured daily start time; IN_FLIGHT counts shipments not yet delivered.
Values:DAILYIN_FLIGHT
daily_capacity_start_timestring
For DAILY profiles: HH:mm time at which the daily window resets (24-hour, UTC). Ignored for IN_FLIGHT.
carrier_account_idsstring[]
Carrier account IDs that this profile applies to.
statusstring
Profile status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

Responses

200Capacity profile updated, and its stored creation_date cleared. The response echoes the profile as sent, with creation_date and update_date set to null.Schema: capacity-profile-dto

profile_idstring
Carriyo-issued identifier for the capacity profile. Server-assigned on create.
profile_namestringrequired
Human-readable name for the profile.
capacity_typestringrequired
Capacity-counting mode: DAILY resets at the configured daily start time; IN_FLIGHT counts shipments not yet delivered.
Values:DAILYIN_FLIGHT
daily_capacity_start_timestring
For DAILY profiles: HH:mm time at which the daily window resets (24-hour, UTC). Ignored for IN_FLIGHT.
carrier_account_idsstring[]
Carrier account IDs that this profile applies to.
statusstring
Profile status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

400

The request was rejected. One of:

profile_name is missing or empty, or capacity_type is missing.
another capacity profile already uses this profile_name.
no capacity profile with this id exists.

500The body had no profile_id. The change was saved before the failure, so treat this as a completed write and do not retry it.

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

delete/capacities/{id}

Delete capacity profile

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Permanently delete a capacity profile.

What happens. It depends on what the profile is attached to:

a profile with rules and no assigned carrier accounts is deleted together with its rules.
a profile with assigned carrier accounts and no rules is deleted, and the accounts are unassigned from it.
a profile with both is rejected.

Path parameters

Name	Type	Required	Description
id	string	Yes	Capacity profile ID.

Headers

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

Responses

200Capacity profile deleted. Response body is empty.

400

The request was rejected. One of:

the profile has rules and is also assigned to carrier accounts. Remove the rules or unassign the accounts first.
no capacity profile with this id exists.

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

post/capacities/{id}/assign

Assign carrier accounts to capacity profile

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Replace the list of carrier accounts assigned to the capacity profile. The request body is the full set; accounts not in the list are unassigned.

Path parameters

Name	Type	Required	Description
id	string	Yes	Capacity profile ID.

Headers

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

Request body

Content type: application/jsonrequired

Responses

200Assignment saved. Returns the capacity profile with its carrier_account_ids.Schema: capacity-profile-dto

profile_idstring
Carriyo-issued identifier for the capacity profile. Server-assigned on create.
profile_namestringrequired
Human-readable name for the profile.
capacity_typestringrequired
Capacity-counting mode: DAILY resets at the configured daily start time; IN_FLIGHT counts shipments not yet delivered.
Values:DAILYIN_FLIGHT
daily_capacity_start_timestring
For DAILY profiles: HH:mm time at which the daily window resets (24-hour, UTC). Ignored for IN_FLIGHT.
carrier_account_idsstring[]
Carrier account IDs that this profile applies to.
statusstring
Profile status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).

400No capacity profile with this id exists.

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

post/capacities/{profile_id}/rules

Add capacity rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Add a new capacity rule to an existing capacity profile. The rule name must be unique within the profile.

Path parameters

Name	Type	Required	Description
profile_id	string	Yes	Capacity profile ID.

Headers

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

Request body

Content type: application/jsonSchema: capacity-rule-dtorequired

capacity_idstring
Carriyo-issued identifier for the capacity rule. Server-assigned on create.
capacity_profile_idstring
ID of the parent capacity profile.
namestringrequired
Human-readable name for the rule.
entity_typestringrequired
Shipment direction the rule applies to. SHIPMENT for outbound shipments, REVERSE_SHIPMENT for returns; rulesets name the same two directions FORWARD and REVERSE.
Values:SHIPMENTREVERSE_SHIPMENT
sequenceintegerrequired
Rule evaluation order within the profile. Lower values evaluate first.
thresholdintegerrequired
Maximum number of shipments allowed under this rule before capacity is considered full.
daily_capacity_start_timestring
Overrides the profile-level start time for this rule (HH:mm, UTC). Only meaningful when the parent profile is DAILY.
daysarray
Days of the week when the rule applies.
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
delivery_typestring-condition-field
Match shipment delivery_type.
order_typestring-condition-field
Match shipment order_type.
creation_source_typestring-condition-field
Match shipment.creation_source.source_type.
update_source_typestring-condition-field
Match shipment.update_source.source_type.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is one custom-attribute condition; all entries are AND-combined.
special_start_datestringformat: date-time
Optional special capacity window start (ISO 8601).
special_end_datestringformat: date-time
Optional special capacity window end (ISO 8601).
creation_datestringformat: date-time
update_datestringformat: date-time

Responses

201Created.Schema: capacity-rule-dto

capacity_idstring
Carriyo-issued identifier for the capacity rule. Server-assigned on create.
capacity_profile_idstring
ID of the parent capacity profile.
namestringrequired
Human-readable name for the rule.
entity_typestringrequired
Shipment direction the rule applies to. SHIPMENT for outbound shipments, REVERSE_SHIPMENT for returns; rulesets name the same two directions FORWARD and REVERSE.
Values:SHIPMENTREVERSE_SHIPMENT
sequenceintegerrequired
Rule evaluation order within the profile. Lower values evaluate first.
thresholdintegerrequired
Maximum number of shipments allowed under this rule before capacity is considered full.
daily_capacity_start_timestring
Overrides the profile-level start time for this rule (HH:mm, UTC). Only meaningful when the parent profile is DAILY.
daysarray
Days of the week when the rule applies.
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
delivery_typestring-condition-field
Match shipment delivery_type.
order_typestring-condition-field
Match shipment order_type.
creation_source_typestring-condition-field
Match shipment.creation_source.source_type.
update_source_typestring-condition-field
Match shipment.update_source.source_type.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is one custom-attribute condition; all entries are AND-combined.
special_start_datestringformat: date-time
Optional special capacity window start (ISO 8601).
special_end_datestringformat: date-time
Optional special capacity window end (ISO 8601).
creation_datestringformat: date-time
update_datestringformat: date-time

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

get/capacities/{profile_id}/rules

List capacity rules

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

List the capacity rules in the specified capacity profile. The list is not sorted; order the rules by sequence to get the evaluation order.

Path parameters

Name	Type	Required	Description
profile_id	string	Yes	Capacity profile ID.

Headers

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

Responses

200The capacity rules in the profile. Empty when the profile has no rules.

An array of capacity-rule-dto. Each item has the following fields:

capacity_idstring
Carriyo-issued identifier for the capacity rule. Server-assigned on create.
capacity_profile_idstring
ID of the parent capacity profile.
namestringrequired
Human-readable name for the rule.
entity_typestringrequired
Shipment direction the rule applies to. SHIPMENT for outbound shipments, REVERSE_SHIPMENT for returns; rulesets name the same two directions FORWARD and REVERSE.
Values:SHIPMENTREVERSE_SHIPMENT
sequenceintegerrequired
Rule evaluation order within the profile. Lower values evaluate first.
thresholdintegerrequired
Maximum number of shipments allowed under this rule before capacity is considered full.
daily_capacity_start_timestring
Overrides the profile-level start time for this rule (HH:mm, UTC). Only meaningful when the parent profile is DAILY.
daysarray
Days of the week when the rule applies.
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
delivery_typestring-condition-field
Match shipment delivery_type.
order_typestring-condition-field
Match shipment order_type.
creation_source_typestring-condition-field
Match shipment.creation_source.source_type.
update_source_typestring-condition-field
Match shipment.update_source.source_type.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is one custom-attribute condition; all entries are AND-combined.
special_start_datestringformat: date-time
Optional special capacity window start (ISO 8601).
special_end_datestringformat: date-time
Optional special capacity window end (ISO 8601).
creation_datestringformat: date-time
update_datestringformat: date-time

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

patch/capacities/{profile_id}/rules/sequences

Update capacity rules sequence

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Set the evaluation order of the capacity rules in a profile. Rules with a lower sequence are evaluated first.

What to send. One entry per rule to reorder, with the rule's capacity_id as rule_id and its new sequence. Rules you leave out keep their sequence. An entry whose rule_id is not in the profile is ignored.

Path parameters

Name	Type	Required	Description
profile_id	string	Yes	Capacity profile ID.

Headers

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

Request body

Content type: application/jsonSchema: sequences-requestrequired

An array of sequences-request. Each item has the following fields:

rule_idstring
sequencenumber

Responses

200Sequences saved. The response echoes the request body.Schema: sequences-request

An array of sequences-request. Each item has the following fields:

rule_idstring
sequencenumber

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

get/capacities/{profile_id}/rules/{rule_id}

Get capacity rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Return a single capacity rule from the specified profile.

Path parameters

Name	Type	Required	Description
profile_id	string	Yes	Capacity profile ID.
rule_id	string	Yes	Capacity rule ID, the rule's `capacity_id`.

Headers

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

Responses

200Returns the requested capacity rule.Schema: capacity-rule-dto

capacity_idstring
Carriyo-issued identifier for the capacity rule. Server-assigned on create.
capacity_profile_idstring
ID of the parent capacity profile.
namestringrequired
Human-readable name for the rule.
entity_typestringrequired
Shipment direction the rule applies to. SHIPMENT for outbound shipments, REVERSE_SHIPMENT for returns; rulesets name the same two directions FORWARD and REVERSE.
Values:SHIPMENTREVERSE_SHIPMENT
sequenceintegerrequired
Rule evaluation order within the profile. Lower values evaluate first.
thresholdintegerrequired
Maximum number of shipments allowed under this rule before capacity is considered full.
daily_capacity_start_timestring
Overrides the profile-level start time for this rule (HH:mm, UTC). Only meaningful when the parent profile is DAILY.
daysarray
Days of the week when the rule applies.
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
delivery_typestring-condition-field
Match shipment delivery_type.
order_typestring-condition-field
Match shipment order_type.
creation_source_typestring-condition-field
Match shipment.creation_source.source_type.
update_source_typestring-condition-field
Match shipment.update_source.source_type.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is one custom-attribute condition; all entries are AND-combined.
special_start_datestringformat: date-time
Optional special capacity window start (ISO 8601).
special_end_datestringformat: date-time
Optional special capacity window end (ISO 8601).
creation_datestringformat: date-time
update_datestringformat: date-time

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

put/capacities/{profile_id}/rules/{rule_id}

Update capacity rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Replace a capacity rule.

What to send. The body fully replaces the stored rule: conditions and days you omit are removed from the rule.

Path parameters

Name	Type	Required	Description
profile_id	string	Yes	Capacity profile ID.
rule_id	string	Yes	Capacity rule ID, the rule's `capacity_id`.

Headers

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

Request body

Content type: application/jsonSchema: capacity-rule-dtorequired

capacity_idstring
Carriyo-issued identifier for the capacity rule. Server-assigned on create.
capacity_profile_idstring
ID of the parent capacity profile.
namestringrequired
Human-readable name for the rule.
entity_typestringrequired
Shipment direction the rule applies to. SHIPMENT for outbound shipments, REVERSE_SHIPMENT for returns; rulesets name the same two directions FORWARD and REVERSE.
Values:SHIPMENTREVERSE_SHIPMENT
sequenceintegerrequired
Rule evaluation order within the profile. Lower values evaluate first.
thresholdintegerrequired
Maximum number of shipments allowed under this rule before capacity is considered full.
daily_capacity_start_timestring
Overrides the profile-level start time for this rule (HH:mm, UTC). Only meaningful when the parent profile is DAILY.
daysarray
Days of the week when the rule applies.
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
delivery_typestring-condition-field
Match shipment delivery_type.
order_typestring-condition-field
Match shipment order_type.
creation_source_typestring-condition-field
Match shipment.creation_source.source_type.
update_source_typestring-condition-field
Match shipment.update_source.source_type.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is one custom-attribute condition; all entries are AND-combined.
special_start_datestringformat: date-time
Optional special capacity window start (ISO 8601).
special_end_datestringformat: date-time
Optional special capacity window end (ISO 8601).
creation_datestringformat: date-time
update_datestringformat: date-time

Responses

200Capacity rule updated. The response echoes the rule as sent, without capacity_id, creation_date or update_date.Schema: capacity-rule-dto

capacity_idstring
Carriyo-issued identifier for the capacity rule. Server-assigned on create.
capacity_profile_idstring
ID of the parent capacity profile.
namestringrequired
Human-readable name for the rule.
entity_typestringrequired
Shipment direction the rule applies to. SHIPMENT for outbound shipments, REVERSE_SHIPMENT for returns; rulesets name the same two directions FORWARD and REVERSE.
Values:SHIPMENTREVERSE_SHIPMENT
sequenceintegerrequired
Rule evaluation order within the profile. Lower values evaluate first.
thresholdintegerrequired
Maximum number of shipments allowed under this rule before capacity is considered full.
daily_capacity_start_timestring
Overrides the profile-level start time for this rule (HH:mm, UTC). Only meaningful when the parent profile is DAILY.
daysarray
Days of the week when the rule applies.
statusstring
Rule status.
Values:ACTIVEINACTIVEDELETED
dropoff_v2geography-condition-field
Match shipment dropoff country / state / city / area.
dropoff_partner_location_idsstring-condition-field
Match shipment dropoff partner location IDs.
dropoff_postcodestring-condition-field
Match shipment dropoff postcode.
pickup_v2geography-condition-field
Match shipment pickup country / state / city / area.
pickup_partner_location_idsstring-condition-field
Match shipment pickup partner location IDs.
pickup_postcodestring-condition-field
Match shipment pickup postcode.
delivery_typestring-condition-field
Match shipment delivery_type.
order_typestring-condition-field
Match shipment order_type.
creation_source_typestring-condition-field
Match shipment.creation_source.source_type.
update_source_typestring-condition-field
Match shipment.update_source.source_type.
custom_conditions_v2custom-attributes-condition-field[]
Match against shipment.custom_attributes. Each entry is one custom-attribute condition; all entries are AND-combined.
special_start_datestringformat: date-time
Optional special capacity window start (ISO 8601).
special_end_datestringformat: date-time
Optional special capacity window end (ISO 8601).
creation_datestringformat: date-time
update_datestringformat: date-time

400

The request was rejected. One of:

name is missing or empty, or entity_type, sequence or threshold is missing.
another rule in the profile already uses this name.
a pickup or dropoff location condition is combined with a geography or postcode condition for the same side.
no rule with this rule_id exists in the profile.

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

delete/capacities/{profile_id}/rules/{rule_id}

Delete capacity rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Permanently delete a capacity rule from the profile. The remaining rules keep their sequence.

Path parameters

Name	Type	Required	Description
profile_id	string	Yes	Capacity profile ID.
rule_id	string	Yes	Capacity rule ID, the rule's `capacity_id`.

Headers

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

Responses

200Capacity rule deleted. Response body is empty.

400No rule with this rule_id exists in the profile.

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

Document Settings

Document settings configure templates and formats for shipment documents (labels, manifests, proofs of delivery).

4 operations · 0 objects

post/document-settings

Create document setting

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Create a document setting for the tenant. A document setting registers a document type (commercial invoice, packing list, label, manifest, POD) along with its format, template, and whether it can be uploaded to the carrier. Document uploads on shipments must match an existing setting.

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: document-requestrequired

namestringrequired
Human-readable name for the document setting. Unique within the tenant.
formatstring
Output format of the rendered document.
Values:pdf
typestringrequired
Whether this is a single document or a group that renders the settings listed in assigned_documents.
Values:documentgroup
shipment_typestring
Shipment entity type the document applies to.
Values:FORWARDREVERSECONSOLIDATED
document_typestring
High-level document category.
Values:commercial_invoicepacking_listcustomer_receiptgift_messagelabeldelivery_advicemanifestqr_codecertificatepick_listother
entity_typestring
Entity the document applies to (DocumentEntityType). Only SHIPMENT and RETURN_REQUEST are supported.
Values:SHIPMENTRETURN_REQUEST
template_namestring
Name of the rendering template stored in the document service.
assigned_documentsstring[]
Identifiers of related document settings that should be rendered alongside this one.
quick_print_enabledboolean
True to expose this document on the dashboard's quick-print menu.
uploaded_documentboolean
True when the template was uploaded by the user rather than supplied by Carriyo.
statusstring
Document setting status.
Values:ACTIVEINACTIVEDELETED

Responses

200Document setting created.Schema: document-settings

tenantIdstring
Tenant identifier.
documentIdstring
Carriyo-issued identifier for the document setting, prefixed with the type it was created with (e.g. document~3f2a9c1e-5b7d-4e8a-9c06-1d2f4a6b8c0e).
namestring
Human-readable name.
formatstring
Output format.
Values:pdf
typestring
Whether this is a single document or a group of other document settings.
Values:documentgroup
shipmentTypestring
Shipment entity type.
Values:FORWARDREVERSECONSOLIDATED
documentTypestring
Document category.
Values:commercial_invoicepacking_listcustomer_receiptgift_messagelabeldelivery_advicemanifestqr_codecertificatepick_listother
entityTypestring
Entity the document applies to (DocumentEntityType). Only SHIPMENT and RETURN_REQUEST are supported.
Values:SHIPMENTRETURN_REQUEST
templateNamestring
Rendering template name.
assignedDocumentsstring[]
Identifiers of the document settings rendered by a group.
quickPrintEnabledboolean
True if exposed on the dashboard quick-print menu.
uploadedDocumentboolean
True if user-uploaded.
statusstring
Document setting status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).
updatedByUserstring
User identifier (typically email) of the last updater.

400

The request was rejected. One of:

name is missing or empty, or type is missing.
entity_type is not SHIPMENT or RETURN_REQUEST.
a document setting with the same name already exists.

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

get/document-settings

List document settings

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Return all document settings configured for the tenant.

Headers

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

Responses

200The document settings configured for the tenant.

An array of document-settings. Each item has the following fields:

tenantIdstring
Tenant identifier.
documentIdstring
Carriyo-issued identifier for the document setting, prefixed with the type it was created with (e.g. document~3f2a9c1e-5b7d-4e8a-9c06-1d2f4a6b8c0e).
namestring
Human-readable name.
formatstring
Output format.
Values:pdf
typestring
Whether this is a single document or a group of other document settings.
Values:documentgroup
shipmentTypestring
Shipment entity type.
Values:FORWARDREVERSECONSOLIDATED
documentTypestring
Document category.
Values:commercial_invoicepacking_listcustomer_receiptgift_messagelabeldelivery_advicemanifestqr_codecertificatepick_listother
entityTypestring
Entity the document applies to (DocumentEntityType). Only SHIPMENT and RETURN_REQUEST are supported.
Values:SHIPMENTRETURN_REQUEST
templateNamestring
Rendering template name.
assignedDocumentsstring[]
Identifiers of the document settings rendered by a group.
quickPrintEnabledboolean
True if exposed on the dashboard quick-print menu.
uploadedDocumentboolean
True if user-uploaded.
statusstring
Document setting status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).
updatedByUserstring
User identifier (typically email) of the last updater.

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

put/document-settings/{documentId}

Update document setting

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Update a document setting.

What to send. name, type and quick_print_enabled are always replaced; quick_print_enabled becomes false when omitted.

Which other fields change. It depends on the type you send:

document replaces format, document_type, shipment_type, entity_type, template_name, status and uploaded_document. Any of these you omit is cleared, except status, which returns to ACTIVE, and uploaded_document, which becomes false.
group replaces assigned_documents only, and leaves the fields above as stored.

Path parameters

Name	Type	Required	Description
documentId	string	Yes	Document setting ID.

Headers

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

Request body

Content type: application/jsonSchema: document-requestrequired

namestringrequired
Human-readable name for the document setting. Unique within the tenant.
formatstring
Output format of the rendered document.
Values:pdf
typestringrequired
Whether this is a single document or a group that renders the settings listed in assigned_documents.
Values:documentgroup
shipment_typestring
Shipment entity type the document applies to.
Values:FORWARDREVERSECONSOLIDATED
document_typestring
High-level document category.
Values:commercial_invoicepacking_listcustomer_receiptgift_messagelabeldelivery_advicemanifestqr_codecertificatepick_listother
entity_typestring
Entity the document applies to (DocumentEntityType). Only SHIPMENT and RETURN_REQUEST are supported.
Values:SHIPMENTRETURN_REQUEST
template_namestring
Name of the rendering template stored in the document service.
assigned_documentsstring[]
Identifiers of related document settings that should be rendered alongside this one.
quick_print_enabledboolean
True to expose this document on the dashboard's quick-print menu.
uploaded_documentboolean
True when the template was uploaded by the user rather than supplied by Carriyo.
statusstring
Document setting status.
Values:ACTIVEINACTIVEDELETED

Responses

200Document setting updated.Schema: document-settings

tenantIdstring
Tenant identifier.
documentIdstring
Carriyo-issued identifier for the document setting, prefixed with the type it was created with (e.g. document~3f2a9c1e-5b7d-4e8a-9c06-1d2f4a6b8c0e).
namestring
Human-readable name.
formatstring
Output format.
Values:pdf
typestring
Whether this is a single document or a group of other document settings.
Values:documentgroup
shipmentTypestring
Shipment entity type.
Values:FORWARDREVERSECONSOLIDATED
documentTypestring
Document category.
Values:commercial_invoicepacking_listcustomer_receiptgift_messagelabeldelivery_advicemanifestqr_codecertificatepick_listother
entityTypestring
Entity the document applies to (DocumentEntityType). Only SHIPMENT and RETURN_REQUEST are supported.
Values:SHIPMENTRETURN_REQUEST
templateNamestring
Rendering template name.
assignedDocumentsstring[]
Identifiers of the document settings rendered by a group.
quickPrintEnabledboolean
True if exposed on the dashboard quick-print menu.
uploadedDocumentboolean
True if user-uploaded.
statusstring
Document setting status.
Values:ACTIVEINACTIVEDELETED
creation_datestringformat: date-time
Creation timestamp (ISO 8601).
update_datestringformat: date-time
Last update timestamp (ISO 8601).
updatedByUserstring
User identifier (typically email) of the last updater.

400

The request was rejected. One of:

name is missing or empty, or type is missing.
entity_type is not SHIPMENT or RETURN_REQUEST.
another document setting already uses this name.
no document setting with this documentId exists.

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

delete/document-settings/{documentId}

Delete document setting

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Permanently delete a document setting. Existing shipment documents tied to this setting are not removed retroactively, but new uploads referencing it are no longer accepted.

Path parameters

Name	Type	Required	Description
documentId	string	Yes	Document setting ID.

Headers

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

Responses

200Document setting deleted. Response body is empty.

400No document setting with this documentId exists.

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>