API reference

Orders API

The Carriyo Orders API manages the customer order lifecycle from creation through fulfillment handoff. Create orders with line items and delivery details, split them across fulfillment locations, and cancel or update them before they ship.

Before you start

Every request carries Authorization: Bearer <token>, x-api-key and tenant-id; see the Authentication API.
merchant is the merchant's identifier, an uppercase code such as ACME, not its display name.
Automatic allocation is off until the tenant's order management settings exist with enable_automatic_order_allocation; until then every order is created in open.
Allocation needs at least one location whose fulfillment coverage includes the delivery or collection address.

Order references

Every endpoint that takes an order in the path accepts either order_id, Carriyo's identifier, or partner_order_reference, your own. The value is matched against order_id first, then partner_order_reference; to keep the two from colliding, a partner_order_reference equal to an existing order_id is rejected with 400, so avoid partner references that could look like Carriyo ids. Fulfillment orders in the path work the same way with fulfillment_order_id and partner_fulfillment_order_reference; when more than one fulfillment order on the order carries the reference you pass, the request fails with 400, so use the id instead.

Idempotency

Write endpoints accept an optional Idempotency-Key request header for safe request replay when your integration retries after uncertain network outcomes. Replayed responses include Idempotent-Replayed: true. See https://carriyo.com/docs/api/idempotency/ for the full contract.

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

Orders

A customer order: the line items, customer and addresses, payment, and the fulfillment orders that carry the items to the customer.

12 operations · 1 object

Object

The Order object

The Order object represents a customer order in Carriyo — line items the customer purchased, shipping and billing addresses, payment, and the references that tie back to your e-commerce or OMS system.

An Order doesn't directly book a shipment. Instead, Carriyo splits the Order into one or more fulfillment orders allocated across your locations, and each fulfillment order produces one or more Shipments. For the full relationship model, see the Domain model.

Properties

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

Create order — POST /orders
List orders — GET /orders
Get order — GET /orders/{order_id}
Update order — PUT /orders/{order_id}
E-commerce orders guide — full integration walkthrough

post/orders

Create order

Creates an order with its line items, customer and delivery details, and allocates it to fulfillment locations.

What happens.

Carriyo validates the request and creates the order.
Fulfillment orders come from your fulfillment_orders, or from automatic allocation when you omit them. Allocation completes before the response.
With inventory management enabled, stock is reserved for the allocated items.
The ORDER_CREATE webhook fires.

The response status is derived from the fulfillment orders: allocated when every fulfillment order has a location, partially_allocated when only some do, and open when none has one. A hold rule can return the order on_hold.

Validation problems on line items, addresses or fulfillment orders do not reject the request. They are recorded in error_details on the created order.

Line items. Each line is resolved against the product catalog by product_ref, then sku, then product_id. The response carries Carriyo's product_id and the product's inventory_key on every resolved line.

Delivery method. Each fulfillment order has one delivery_method:

DELIVERY uses delivery_address and delivery_schedule.
COLLECTION uses customer_collection_address and customer_collection_schedule.
DIGITAL needs neither.

The top-level delivery fields are request-only conveniences and are not stored on the order itself. They are copied onto the fulfillment orders Carriyo creates when you omit fulfillment_orders. To set them per fulfillment order, put them inside each entry.

An entry without its own delivery fields inherits the top-level delivery_method, delivery_type and delivery_option, then the top-level address and schedule for its method. Fields the entry sets always win. This inheritance happens on create only.

Allocation.

Manual. A fulfillment_orders entry that names a location is left as sent.
Automatic. Entries with no location, and every fulfillment order when you omit fulfillment_orders, are allocated by the engine, provided enable_automatic_order_allocation is on in the order management settings; DIGITAL entries are never allocated. Stock counts only when inventory management is enabled. Radius coverage needs coords on the reference address.

With automatic allocation off, entries that name a location are allocated and the rest are open with fulfillment_location_missing in their error_details.

When no candidate can supply an item:

with the order management setting allow_partial_order_allocation on, the unsupplied items move to a separate fulfillment order whose items are cancelled, and the order still reports allocated;
otherwise the fulfillment order stays as it was, with auto_allocation_failed in its error_details and an allocation_failure_reason on each item. A coverage miss reports OUT_OF_STOCK.

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.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

Content type: application/jsonSchema: create-order-requestrequired

merchantstringrequired
The merchant identifier for this order.
partner_order_referencestringrequired
Your system's order reference. Must be unique within your tenant and must not equal an existing Carriyo order_id; either case is rejected with a 400.
languagestring
Language code for customer communications (e.g., "en", "ar").
order_datestringformat: date-time
The date when the order was placed (ISO 8601 format).
sales_channelstring
The sales channel where the order originated (e.g., "web", "mobile", "store").
delivery_methodstring
The delivery method to apply to all auto-allocated fulfillment orders. Request-only field, stored on each fulfillment order, not on the Order.
Values:DELIVERYCOLLECTIONDIGITAL
delivery_typestring
Service level such as standard, express or same_day; the values are configured per tenant. Applies when delivery_method is DELIVERY. Request-only: stored on each fulfillment order, not on the order.
delivery_optiondelivery-option
The chosen delivery option reference. Carriyo resolves the underlying carrier and service level from this reference.
delivery_addressaddress
Where the order is delivered. Applies when delivery_method is DELIVERY. Request-only: stored on each fulfillment order, not on the order.
delivery_schedulefo-schedule
Scheduled delivery window. Applies when delivery_method is DELIVERY. Request-only: stored on each fulfillment order, not on the order.
customer_collection_addressaddress
Store, locker or pickup point the customer collects from. Applies when delivery_method is COLLECTION. Request-only: stored on each fulfillment order, not on the order.
customer_collection_schedulefo-schedule
Window during which the customer can collect. Applies when delivery_method is COLLECTION. Request-only: stored on each fulfillment order, not on the order.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
paymentorder-payment
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
Discounts applied to the order.
line_itemsline-item[]
Products ordered with quantities and prices.
fulfillment_ordersfulfillment-order-request[]
Optional explicit fulfillment order specifications. When omitted, Carriyo auto-allocates fulfillment orders based on inventory and rules.
shipping_linesshipping-line[]
Shipping methods and costs.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.

Responses

200Order created successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

400Schema: error-response

The request was rejected. One of:

partner_order_reference already exists in the tenant or equals an existing order_id.
the merchant is unknown.
the account's order quota is exhausted.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

get/orders

List orders

Returns a page of orders matching the search and filter parameters.

Behavior. search_string matches substrings of the order id and partner order reference.

Each request through the API counts one against the account's monthly order-list quota, a separate allowance from the order quota. The counter resets each calendar month, and a request that fails with a server error is not counted.

Related: Order status codes

Query parameters

Name	Type	Required	Description
search_string	string	No	The search string to find orders using order data such as order id and partner order reference.
merchant	string	No	The merchant parameter filters orders for a given merchant. This parameter can be used multiple times to filter results for multiple merchants.
creation_date_from	string	No	The start date in ISO 8601 format to filter the results using order creation date.
creation_date_to	string	No	The end date in ISO 8601 format to filter the results using order creation date.
update_date_from	string	No	The start date in ISO 8601 format to filter results, returning orders that were either created OR updated during this time period.
update_date_to	string	No	The end date in ISO 8601 format to filter results, returning orders that were either created OR updated during this time period.
page	string	No	The page number of the result set, starting from 0. Defaults to the first page (page 0).
page_size	string	No	The number of results to be included in the response, ranging from 10 to 100. Defaults to page size of 10.

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 orders.Schema: order-list

ordersorder[]
paginationobject
Position of this page in the result set.

429The monthly order-list quota is exhausted; the message states the limit.Schema: middleware-error-response

errorstring
A human-readable message describing why the request failed.
errorCodestring
A short machine-readable name for the failure, such as BadRequest, Forbidden, NotFound or TooManyRequests.

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

get/orders/{orderReference}

Get order

Returns an order by order_id or partner_order_reference, with its fulfillment orders and line items.

Related: Order status codes

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.

Headers

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

Responses

200Order retrieved successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

404Order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

patch/orders/{orderReference}

Update order

Applies a partial update to an order; line_items and fulfillment_orders are replaced as whole arrays.

Preconditions. The order must not be cancelled or on hold. Orders in processing, fulfilled or closed can still be updated.

What happens. The changes below are applied and the ORDER_UPDATE webhook fires.

Simple fields. These change only when present in the request; an empty string is ignored, not applied:

partner_order_reference, order_date, merchant, language, sales_channel
taxes_included, duties_included
billing_address, customer
payment, discount_applications, shipping_lines

custom_attributes is merged per key, and a null value removes the key.

The order stores no delivery address of its own; delivery details live inside each fulfillment_orders entry. To change where a fulfillment order delivers after allocation, use its address endpoint.

Line items. line_items, when present, replaces the whole list. Include every line item you want to keep. To remove an item after allocation, cancel it on its fulfillment order.

Fulfillment orders. fulfillment_orders, when present, replaces the whole list too:

A fulfillment order left out of the request is removed, even when it has fulfilled items; its pending reservations are released.
One matched by fulfillment_order_id or partner_fulfillment_order_reference is updated.
One with no match is created. Without a location it is left open with fulfillment_location_missing in its error_details; update never runs the allocation engine.

Within a fulfillment order, send only line items in open or allocated status. fulfilled, cancelled and closed items are preserved automatically; one that is re-sent is not rejected but added again as a new pending item alongside the preserved one. Quantity reductions are recorded in removed_quantities.

A fulfillment order line item that matches no order line item is recorded in the fulfillment order's error_details rather than rejected.

Inventory. With inventory management enabled, reservations follow the allocation changes:

stock is reserved for new fulfillment order allocations;
stock is released for removed allocations;
reservations are adjusted for quantity changes.

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.

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.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

Content type: application/jsonSchema: update-order-requestrequired

partner_order_referencestring
Your system's order reference. Must be unique within your tenant and must not equal an existing Carriyo order_id; either case is rejected with a 400.
order_datestringformat: date-time
The date when the order was placed (ISO 8601 format).
merchantstring
The merchant identifier.
languagestring
Language code for customer communications.
sales_channelstring
The sales channel where the order originated.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
paymentorder-payment
discount_applicationsdiscount-application[]
shipping_linesshipping-line[]
line_itemsupdate-line-item-request[]
Full replacement - If provided, completely replaces all existing line items. Include all line items you want to keep.
fulfillment_ordersupdate-fulfillment-order-request[]
Full replacement with preservation rules. ⚠️ Critical: Any fulfillment order NOT included in this array will be PERMANENTLY REMOVED. For each FO's line_items: - Only include items with pending statuses (open, allocated, pick_in_progress, picked, pack_in_progress) - Items with terminal statuses (fulfilled, cancelled, closed) are automatically preserved
delivery_optiondelivery-option
The chosen delivery option reference. Carriyo resolves the underlying carrier and service level from this reference.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.

Responses

200Order updated successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

400Schema: error-response

The request was rejected. One of:

the order is cancelled.
the order is on hold.
another update changed the order first; re-read and retry.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

post/orders/{orderReference}/cancel

Cancel order

Cancels an order and every fulfillment order on it.

Preconditions. The order must be open, partially_allocated, allocated or on_hold; cancelling a held order releases the hold. For an order in processing, fulfilled or closed the request succeeds but nothing changes: the unchanged order is returned and the ORDER_CANCEL webhook still fires, so check status in the response.

What happens.

Every fulfillment order line item becomes cancelled with the cancellation_reason you supply.
Open picks are cancelled.
The order status becomes cancelled.
The ORDER_CANCEL webhook fires.

Order line item quantities are left as they were.

Inventory. With inventory management enabled and a fulfillment_location set on the fulfillment order, reserved is reduced by the cancelled quantity.

Related: Order status codes

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.

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.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

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

cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother

Responses

200Order cancelled successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

400The order is already cancelled.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

post/orders/{orderReference}/redact

Redact order

Anonymises the personal data on an order and on the dropoff side of every linked shipment. The change is irreversible.

Preconditions. None. The order can be in any status, including on hold.

Webhooks. No webhook fires.

Related: What redaction removes

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.

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`.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Responses

200Order redacted successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

404Order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

get/orders/{orderReference}/activity

List order activity

Returns a paginated timeline of everything that has happened to an order.

Behavior. Each entry comes from one of three sources:

Change logs — field-level edits, in changes.
System logs — API calls and internal events, with timing and response code.
Notifications — customer notifications, in notification, with request_type NOTIFICATION.

A change log and the system log that caused it merge into one entry. A system log with no change log appears on its own, without changes.

Housekeeping fields that change on every write, such as update_date and update_source, are left out of changes.

Related: Order webhook events

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.

Query parameters

Name	Type	Required	Description
page_num	integer	No	Page of the timeline to return. Values below 1 fall back to 1.
rows_per_page	integer	No	Entries per page. Values above 100 are capped at 100.
sort	string	No	Orders entries by timestamp. Defaults to newest first.
source	array	No	Filters entries by what triggered them. Comma-separated, any match: `source=user,api`. - `all`: no filtering (default) - `user`: Dashboard and Fulfillment App activity - `api`: direct API calls - `webhook`: webhook deliveries and retries - `system`: everything else, such as carrier callbacks and internal services Unrecognized values are ignored.

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

200Activity timeline retrieved successfully.Schema: activity-response

itemsactivity-entry[]
The activity entries for the requested page.
totalinteger
Total entries in the timeline after filtering, across all pages.
page_numinteger
The page returned.
rows_per_pageinteger
Entries per page used for this response.
truncatedboolean
True when the filtered timeline reaches 1000 entries. Each source is read up to its own limit before merging, so one source can be missing older entries while another is complete.

404Order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

post/orders/{orderReference}/on-hold

Hold order

Puts an order on hold so that it cannot be updated or fulfilled until the hold is released.

Preconditions. The order must be open, partially_allocated or allocated and not already on hold. A fulfillment order already on hold does not block the call; its hold is absorbed and released together with the order hold.

What happens.

The order status becomes on_hold, and every open or allocated fulfillment order on it shows on_hold too.
on_hold_details records the hold; an earlier hold moves into history.
While the hold is active, updating the order and every fulfillment order operation except cancel return 400.
Cancelling a held order releases the hold.
The ORDER_ON_HOLD webhook fires.

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.

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.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

Content type: application/jsonSchema: on-hold-request

assigned_toassigned-to
The user or team responsible for resolving a hold.
prioritystring
Priority of the hold for whoever works it.
Values:LOWNORMALHIGHURGENT
sla_hoursinteger
Hours allowed to resolve the hold. Carriyo stores the deadline as sla_timestamp.
notesstring
Why the hold was placed.

Responses

200Order placed on hold successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

400Schema: error-response

The request was rejected. One of:

the order is not open, partially_allocated or allocated.
the order is already on hold.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

post/orders/{orderReference}/release-on-hold

Release order hold

Releases an active hold on an order and returns it to the status derived from its fulfillment orders.

Preconditions. The order must be on_hold.

What happens.

The order returns to open, partially_allocated or allocated as derived from its fulfillment orders.
Any hold on the order's individual fulfillment orders is released as well.
on_hold_details is kept with the release details.
The ORDER_RELEASE_ON_HOLD webhook fires.

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.

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.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

Content type: application/jsonSchema: release-on-hold-request

notesstring
Why the hold was released. Stored as release_notes.

Responses

200Hold released successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

400The order is not on_hold.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

post/orders/{orderReference}/fulfill

Fulfill entire order

Fulfills every pending item on the order in one call, whichever fulfillment orders they sit on.

Preconditions. The order may not be on hold, no fulfillment order with pending items may be on hold, and at least one item must be pending. Pending covers open, allocated, pick_in_progress, picked and pack_in_progress.

Open picks and packs. The call is refused while any fulfillment order it would fulfill has a pick that is open, processing or stopped, or a pack that is open or processing. Complete or cancel it first.

Scope. Every fulfillment order with pending items is fulfilled in full. Fulfillment orders with nothing pending are skipped, so an order that was already part fulfilled or part cancelled can still be completed in one call.

You cannot select items; every pending item is fulfilled. To fulfill one fulfillment order, or part of one, use the fulfillment order endpoint instead.

The order status is recalculated and the FULFILLMENT_ORDER_FULFILL webhook fires once for the whole call.

Shipments. Each fulfillment order that requires shipping becomes its own shipment, created and confirmed with the carrier. Two query parameters change that:

create_draft_shipment=true leaves the shipments as drafts for review before booking.
skip_shipping=true fulfills without creating any shipment.

If a shipment cannot be created, the fulfillment order is still fulfilled and records shipment_creation_failed in its error_details; retry it with the ship endpoint. If the carrier booking fails, the shipment is left in error with the reason in its own error_details; fix the cause and reprocess the shipment.

When items close. A fulfillment order requires shipping when its delivery method is DELIVERY, or COLLECTION from a location other than the one fulfilling it. Items close automatically only when it does not require shipping and the order did not come from Shopify. With skip_shipping=true on one that does require shipping, the items stay fulfilled for you to close yourself.

Payment split. When the order carries a payment, this call splits the part of it that it is fulfilling across the shipments it creates:

by item value;
by quantity when items have no prices;
evenly when there is neither.

Items fulfilled by an earlier call and cancelled items are left out, so nothing is collected twice. The last shipment takes the rounding remainder.

A fulfillment order that creates no shipment, because it needs none or because skip_shipping is set, still takes a share, and that share is dropped with it. The shares therefore add up to the whole order payment only when the call fulfills the whole order and every fulfillment order it fulfills creates a shipment.

With no payment on the order, each shipment carries a zeroed payment: no currency, total_amount 0 and pending_amount 0.

Inventory. With inventory management enabled and stock_reduction_timing set to ON_ORDER_FULFILLED, on_hand and reserved are reduced by the fulfilled quantity.

Related: What fulfilling produces

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.

Query parameters

Name	Type	Required	Description
create_draft_shipment	boolean	No	If true, creates draft shipments instead of immediately booking with a carrier.
skip_shipping	boolean	No	If true, fulfills the order without creating any shipment.

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.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

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

carrier_accountcarrier-account-request
Identifies a specific carrier account configured in Carriyo.
deliveryfulfillment-delivery
Scheduling window for a fulfillment.
ship_zonestring
Ship zone applied to the shipments, overriding the zone Carriyo would otherwise derive.

Responses

200Order fulfilled successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

400Schema: error-response

The request was rejected. One of:

the order, or a fulfillment order with pending items, is on hold.
a fulfillment order it would fulfill has an active pick or pack.
nothing is pending.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

post/orders/{orderReference}/unfulfill

Unfulfill entire order

Reverses every fulfillment on the order in one call, returning its items to allocated status.

Preconditions. Neither the order nor any of its fulfillment orders may be on hold, at least one item must be fulfilled, and the order must not have come from the Mirakl Connect connector.

Scope. Fulfillment orders with nothing fulfilled are skipped, so a part fulfilled order can be taken back in one call. To reverse a single fulfillment, use the fulfillment order endpoint instead.

What happens. For every fulfillment on the order, Carriyo:

Cancels the associated shipments, if not already cancelled. A shipment that can no longer be cancelled does not stop the call; its items still return to allocated.
Returns the line items to allocated.
Clears their fulfillment id, shipment ids and partner reference.
Merges items that share the same id and status.
Recalculates the order status.

The FULFILLMENT_ORDER_UNFULFILL webhook fires once for the whole call.

Inventory. With inventory management enabled, on_hand is increased by the unfulfilled quantity; reserved is not changed and stock_reduction_timing is not consulted.

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.

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`.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Responses

200Order unfulfilled successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

400Schema: error-response

The request was rejected. One of:

the order or any of its fulfillment orders is on hold.
nothing on the order is fulfilled.
the order came from the Mirakl Connect connector.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

post/orders/bulk/import

Bulk import orders

Creates or updates several orders in one request; each row is processed independently.

Per row.

A row whose partner_order_reference is new creates an order. A create behaves exactly as Create order, including allocation, reservation and the ORDER_CREATE webhook.
A row matching an existing order updates it when the order is open, partially_allocated or allocated; any other status rejects the row. An update behaves exactly as Update order, including the ORDER_UPDATE webhook.
Rows that share a partner_order_reference within the same request are all rejected.

Processing continues past failed rows.

Limits. The request takes up to 20 orders by default. The limit is configurable per tenant, so chunk larger imports client-side.

Result per row. The response has one entry per row. A rejected row carries the error in reason and no 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`.
Content-Type	application/json	Yes	Media type of the request body.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

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

order_requestscreate-order-request[]
Array of orders to create or update (maximum 20). Existing orders matched by partner_order_reference are updated if in an eligible status.

Responses

200Bulk import processed.

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

partner_order_referencestring
The partner reference from the request, for correlation.
resultstring
created when a new order was created, updated when an existing order was updated, rejected on failure.
Values:createdupdatedrejected
orderorder
The full order object. Present when result is not rejected.
reasonstring
Human-readable detail. null for new creates, "Existing order updated" for updates, or an error message for rejections.

400Schema: error-response

The request was rejected. One of:

the request body is malformed.
the request exceeds the row limit.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

Fulfillment Orders

A group of line items from one order fulfilled from one location with one delivery method. Every operation here except merge takes the order reference followed by the fulfillment order reference.

15 operations · 0 objects

post/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderReference}/fulfill

Fulfill fulfillment order

Marks the items of a fulfillment order as fulfilled and creates a shipment for them.

Preconditions. Neither the fulfillment order nor its order may be on hold, and every named item must be pending. Pending covers open, allocated, pick_in_progress, picked and pack_in_progress.

Open picks and packs. Fulfilling is refused while the fulfillment order has a pick that is open, processing or stopped, or a pack that is open or processing. Complete or cancel it first.

What to send. line_items names the items, each with a quantity no greater than the quantity still pending. Identify each item by the order line item's id, or by product_id, product_ref or sku when that names exactly one line item on the fulfillment order. Omit it, or send no body, to fulfill every pending item at its full quantity. To fulfill every pending item across the whole order, use the order endpoint instead.

The items are marked fulfilled under a new fulfillment id, the order status is recalculated and the FULFILLMENT_ORDER_FULFILL webhook fires.

Shipments. When the fulfillment order requires shipping, its items become one shipment, created and confirmed with the carrier. Two query parameters change that:

create_draft_shipment=true leaves it as a draft for review before booking.
skip_shipping=true fulfills without creating a shipment at all.

If the shipment cannot be created, the fulfillment order is still fulfilled and records shipment_creation_failed in its error_details; retry it with the ship endpoint. If the carrier booking fails, the shipment is left in error with the reason in its own error_details; fix the cause and reprocess the shipment.

Payment split. There is no split: the shipment carries the full order payment, both the order total and the amount to collect on delivery. Only the order endpoint distributes payment across shipments.

Inventory. With inventory management enabled and stock_reduction_timing set to ON_ORDER_FULFILLED, on_hand and reserved are reduced by the fulfilled quantity.

Related: What fulfilling produces

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.
fulfillmentOrderReference	string	Yes	Carriyo `fulfillment_order_id` or your own `partner_fulfillment_order_reference`. The value is matched against `fulfillment_order_id` first, then `partner_fulfillment_order_reference`. A partner reference shared by more than one fulfillment order on the order returns 400. A value matching neither returns 404.

Query parameters

Name	Type	Required	Description
create_draft_shipment	boolean	No	If true, creates a draft shipment instead of immediately booking with a carrier.
skip_shipping	boolean	No	If true, fulfills the order without creating a shipment.

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.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

Content type: application/jsonSchema: create-fulfillment-request

partner_fulfillment_referencestring
Your system's reference for this fulfillment.
line_itemsfo-line-item-ref[]
The line items to fulfill, each with its quantity. Omit to fulfill every pending item at its full quantity.
carrier_accountcarrier-account-request
Identifies a specific carrier account configured in Carriyo.
parcelsparcel-request[]
Parcel details for the shipment.
deliveryfulfillment-delivery
Scheduling window for a fulfillment.
paymentfulfillment-payment
pre_booking_infopre-booking-info
Information about a shipment that has already been booked with a carrier outside Carriyo.
ship_zonestring
Ship zone applied to the shipment, overriding the zone Carriyo would otherwise derive.

Responses

200Fulfillment order fulfilled successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

400Schema: error-response

The request was rejected. One of:

an item carries neither id nor a product identifier.
a product identifier matches no line item on the fulfillment order, or matches more than one.
quantity is missing or below 1.
line_items is empty.
line_items is omitted and nothing on the fulfillment order is pending.
the fulfillment order has an active pick or pack.
an item is not in a pending status.
a quantity exceeds what is pending.
the fulfillment order or its order is on hold.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Order or fulfillment order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

post/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderReference}/unfulfill

Unfulfill fulfillment order

Reverses selected fulfillments on a fulfillment order, returning their items to allocated status.

Preconditions. Neither the fulfillment order nor its order may be on hold, and the order must not have come from the Mirakl Connect connector.

What to send. fulfillment_ids is required and lists the fulfillments to reverse; each must belong to the fulfillment order. partner_fulfillment_order_reference, when sent, replaces the fulfillment order's reference after the reversal. To reverse every fulfillment on the order, use the order endpoint instead.

What happens. For each fulfillment, Carriyo:

Cancels the associated shipments, if not already cancelled. A shipment that can no longer be cancelled does not stop the call; its items still return to allocated.
Returns the line items to allocated.
Clears their fulfillment id, shipment ids and partner reference.
Merges items that share the same id and status.
Recalculates the order status.

The FULFILLMENT_ORDER_UNFULFILL webhook fires once for the whole call.

Inventory. With inventory management enabled, on_hand is increased by the unfulfilled quantity; reserved is not changed and stock_reduction_timing is not consulted.

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.
fulfillmentOrderReference	string	Yes	Carriyo `fulfillment_order_id` or your own `partner_fulfillment_order_reference`. The value is matched against `fulfillment_order_id` first, then `partner_fulfillment_order_reference`. A partner reference shared by more than one fulfillment order on the order returns 400. A value matching neither returns 404.

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.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

Content type: application/jsonSchema: unfulfill-fulfillment-requestrequired

fulfillment_idsstring[]required
The fulfillments to reverse. Each must belong to the fulfillment order.
partner_fulfillment_order_referencestring
Sets a new partner_fulfillment_order_reference on the fulfillment order after the reversal. Omit to keep the current reference.

Responses

200Fulfillment reversed successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

400Schema: error-response

The request was rejected. One of:

fulfillment_ids is missing or empty.
a fulfillment id does not exist on the fulfillment order.
the fulfillment order or its order is on hold.
the order came from the Mirakl Connect connector.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Order or fulfillment order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

post/orders/{orderReference}/fulfillment-orders/merge

Merge fulfillment orders

Moves line items from one fulfillment order into another.

Preconditions.

Neither fulfillment order may contain fulfilled items or have active picks.
Neither fulfillment order nor the order may be on hold.
Both must share the same fulfillment_location, delivery_type, delivery method and delivery_option.

What to send.

source names the fulfillment order and, in line_items, the items and quantities to move; a partial quantity moves and the source keeps the remainder. line_items is required; there is no merge-everything default. Identify each item by the order line item's id, or by product_id, product_ref or sku when that names exactly one line item on the source fulfillment order.
destination names the fulfillment order to receive them.

What happens.

A moved item merges into a matching destination item, or is added as allocated or open depending on whether the destination has a location.
If every item leaves the source, the source fulfillment order is removed.
The order status is recalculated and the FULFILLMENT_ORDER_MERGE webhook fires.

Inventory. Inventory is unchanged; items are only moved between fulfillment orders.

Related: Splits and merges

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.

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.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

Content type: application/jsonSchema: merge-fulfillment-order-requestrequired

sourceobjectrequired
The fulfillment order to merge from.
destinationobjectrequired
The fulfillment order to merge into.

Responses

200Fulfillment orders merged successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

400Schema: error-response

The request was rejected. One of:

an item carries neither id nor a product identifier.
a product identifier matches no line item on the source fulfillment order, or matches more than one.
quantity is missing or below 1.
the source or destination contains fulfilled items.
the source or destination has active picks.
the source or destination, or the order, is on hold.
the two differ in fulfillment_location, delivery_type, delivery method or delivery_option.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Order or fulfillment orders not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

post/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderReference}/split

Split fulfillment order

Moves selected line items from a fulfillment order into a new fulfillment order.

Preconditions. Neither the fulfillment order nor its order may be on hold, and the fulfillment order must have no active picks. Only items in open or allocated status qualify.

What to send. line_items names the items and quantities to move. Identify each item by the order line item's id, or by product_id, product_ref or sku when that names exactly one line item on the fulfillment order.

fulfillment_location, by partner location id or code, or location_id sets the new fulfillment order's location. Omitted, the new fulfillment order takes the original's location.
partner_fulfillment_order_reference sets your reference on the new fulfillment order. Send one: when you omit it the source's reference is copied, and a reference shared by two fulfillment orders can no longer address either.

What happens.

The new fulfillment order gets its own fulfillment_order_id and inherits the delivery details of the original.
Moved items are allocated when a location is set and open otherwise.
The original's quantities are reduced, and items whose quantity reaches zero are removed.
The order status is recalculated and the FULFILLMENT_ORDER_SPLIT webhook fires.

Inventory. With inventory management enabled and a different location supplied, reservations for the moved items move to the new location.

Related: Splits and merges

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.
fulfillmentOrderReference	string	Yes	Carriyo `fulfillment_order_id` or your own `partner_fulfillment_order_reference`. The value is matched against `fulfillment_order_id` first, then `partner_fulfillment_order_reference`. A partner reference shared by more than one fulfillment order on the order returns 400. A value matching neither returns 404.

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.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

Content type: application/jsonSchema: split-fulfillment-requestrequired

line_itemsfo-line-item-ref[]required
The line items to move to the new fulfillment order, each with its quantity.
partner_fulfillment_order_referencestring
Partner reference for the new fulfillment order.
location_idstring
Partner location ID for the new fulfillment order, accepted as a flat alternative to fulfillment_location.
fulfillment_locationfulfillment-location-request
Location for the new fulfillment order, by partner_location_id or partner_location_code; defaults to the original fulfillment order's location.

Responses

200Fulfillment order split successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

400Schema: error-response

The request was rejected. One of:

an item carries neither id nor a product identifier.
a product identifier matches no line item on the fulfillment order, or matches more than one.
quantity is missing or below 1.
an item is fulfilled, cancelled or closed.
a quantity exceeds what the item has.
the fulfillment order or its order is on hold.
the fulfillment order has active picks.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Order or fulfillment order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

post/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderReference}/ship

Ship fulfillment order

Creates a shipment for selected items of a fulfillment order.

Preconditions. Neither the fulfillment order nor its order may be on hold, and the fulfillment order must have a delivery or collection address. Items must be allocated, pick_in_progress, picked, pack_in_progress or fulfilled.

What to send. line_items is required and names the items and quantities to ship; their status does not change. Identify each item by the order line item's id, or by product_id, product_ref or sku when that names exactly one line item on the fulfillment order. The body takes the same fields as Create shipment; omit the carrier account to let automation rules choose.

What happens.

Carriyo creates the shipment.
It confirms the shipment with the carrier, unless create_draft_shipment=true leaves it as a draft for review before booking.
The shipment id is linked to the items.
The FULFILLMENT_ORDER_SHIP_LINE_ITEMS webhook fires.

If the carrier booking fails, the shipment is left in error with the reason in its error_details; fix the cause and reprocess the shipment.

Inventory. Inventory is unchanged; it moves on fulfill and cancel.

Related: What fulfilling produces

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.
fulfillmentOrderReference	string	Yes	Carriyo `fulfillment_order_id` or your own `partner_fulfillment_order_reference`. The value is matched against `fulfillment_order_id` first, then `partner_fulfillment_order_reference`. A partner reference shared by more than one fulfillment order on the order returns 400. A value matching neither returns 404.

Query parameters

Name	Type	Required	Description
create_draft_shipment	boolean	No	If true, creates a draft shipment instead of immediately booking with a 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.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

Content type: application/jsonSchema: ship-fo-line-items-requestrequired

line_itemsfo-line-item-ref[]required
The line items to ship, each with its quantity. Required; the call never defaults to every item.
carrier_accountcarrier-account-request
Identifies a specific carrier account configured in Carriyo.
parcelsparcel-request[]
deliveryfulfillment-delivery
Scheduling window for a fulfillment.
paymentfulfillment-payment
pre_booking_infopre-booking-info
Information about a shipment that has already been booked with a carrier outside Carriyo.
ship_zonestring
Ship zone applied to the shipment, overriding the zone Carriyo would otherwise derive.

Responses

200Shipment created successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

400Schema: error-response

The request was rejected. One of:

line_items is missing or empty.
an item carries neither id nor a product identifier.
a product identifier matches no line item on the fulfillment order, or matches more than one.
quantity is missing or below 1.
an item is open, cancelled or closed.
a quantity exceeds what is available.
the fulfillment order has no delivery or collection address.
the fulfillment order or its order is on hold.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Order or fulfillment order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

patch/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderReference}/update-location

Update fulfillment order location

Reassigns a fulfillment order to a different location.

Preconditions. Neither the fulfillment order nor its order may be on hold, and the fulfillment order must have no active picks.

What to send. fulfillment_location identifies the new location by partner_location_id or partner_location_code, resolved in that order. location_id is accepted as a flat alternative. Omit both to remove the current assignment.

What happens.

Assigning a location: the fulfillment order's location is replaced, open items become allocated, and any earlier allocation failure is cleared.
Removing it: allocated items become open and fulfillment_location_missing is recorded in error_details.
The order status is recalculated and the FULFILLMENT_ORDER_UPDATE_LOCATION webhook fires.

Inventory. With inventory management enabled, reservations are released at the old location and taken at the new one. Stock at the new location is not checked; the reservation is taken regardless.

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.
fulfillmentOrderReference	string	Yes	Carriyo `fulfillment_order_id` or your own `partner_fulfillment_order_reference`. The value is matched against `fulfillment_order_id` first, then `partner_fulfillment_order_reference`. A partner reference shared by more than one fulfillment order on the order returns 400. A value matching neither returns 404.

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.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

Content type: application/jsonSchema: update-location-requestrequired

location_idstring
Partner location ID to move the fulfillment order to, accepted as a flat alternative to fulfillment_location.
fulfillment_locationfulfillment-location-request
The new location for the fulfillment order. When provided, either partner_location_id or partner_location_code is required.

Responses

200Location updated successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

400Schema: error-response

The request was rejected. One of:

the fulfillment order has active picks.
the fulfillment order or its order is on hold.
no location is assigned and none is supplied.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Schema: error-response

The request was rejected. One of:

no order matches the id or reference.
no fulfillment order on it matches the id or reference.
the location cannot be resolved.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

patch/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderReference}/update-delivery-method

Update fulfillment order delivery method

Switches a fulfillment order between DELIVERY, COLLECTION and DIGITAL, setting the matching address and schedule in one call.

Preconditions. The order must be open, partially_allocated or allocated, and neither it nor the fulfillment order may be on hold. delivery_method is required.

What each method sets. The body's address, scheduled_from, scheduled_to and delivery_option are stored according to the new delivery_method:

DELIVERY — address becomes delivery_address; scheduled_from and scheduled_to become delivery_schedule; delivery_option is applied. The collection address and schedule are cleared.
COLLECTION — address becomes customer_collection_address; scheduled_from and scheduled_to become customer_collection_schedule. The delivery address, delivery schedule and delivery_option are cleared.
DIGITAL — the address and schedule are left as they are and delivery_option is cleared.

Whichever method you set, delivery_type is taken from the body, so omitting it clears the existing value.

What happens. The fulfillment order is updated and the FULFILLMENT_ORDER_UPDATE_DELIVERY_METHOD webhook fires.

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.
fulfillmentOrderReference	string	Yes	Carriyo `fulfillment_order_id` or your own `partner_fulfillment_order_reference`. The value is matched against `fulfillment_order_id` first, then `partner_fulfillment_order_reference`. A partner reference shared by more than one fulfillment order on the order returns 400. A value matching neither returns 404.

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.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

Content type: application/jsonSchema: update-fulfillment-order-delivery-method-requestrequired

delivery_methodstringrequired
How the order is delivered to the customer: - DELIVERY: standard delivery to the customer's address (uses delivery_address and delivery_schedule). - COLLECTION: customer collects the order from a specified location (uses customer_collection_address and customer_collection_schedule). - DIGITAL: no physical delivery; the order is fulfilled digitally.
Values:DELIVERYCOLLECTIONDIGITAL
addressaddress
The new address for the fulfillment order. - For DELIVERY: the new delivery address. - For COLLECTION: the new customer collection address. - For DIGITAL: not required.
scheduled_fromstringformat: date-time
Start of the new scheduled window (delivery or customer-collection, depending on delivery_method).
scheduled_tostringformat: date-time
End of the new scheduled window.
delivery_typestring
The delivery service level (e.g., standard, express). Applies when delivery_method is DELIVERY.
delivery_optiondelivery-option
The chosen delivery option reference. Carriyo resolves the underlying carrier and service level from this reference.

Responses

200Delivery method updated successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

400Schema: error-response

The request was rejected. One of:

the order is not open, partially_allocated or allocated.
the fulfillment order or its order is on hold.
delivery_method is missing.
delivery_option does not exist.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Order or fulfillment order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

patch/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderReference}/update-address

Update fulfillment order address

Replaces the address on a fulfillment order according to its current delivery_method.

Preconditions. The fulfillment order must be open or allocated, and neither it nor its order may be on hold. address is required.

What happens.

DELIVERY and DIGITAL: address replaces delivery_address.
COLLECTION: address replaces customer_collection_address.
Allocation is not re-run and reservations are unchanged, even when the new address is outside the current location's coverage; use Allocate fulfillment order if the new address needs a different location.
The FULFILLMENT_ORDER_UPDATE_ADDRESS webhook fires.

To change the method itself, use the delivery-method endpoint first.

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.
fulfillmentOrderReference	string	Yes	Carriyo `fulfillment_order_id` or your own `partner_fulfillment_order_reference`. The value is matched against `fulfillment_order_id` first, then `partner_fulfillment_order_reference`. A partner reference shared by more than one fulfillment order on the order returns 400. A value matching neither returns 404.

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.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

Content type: application/jsonSchema: update-fulfillment-order-address-requestrequired

addressaddressrequired
The new address. Applies to delivery_address when delivery_method is DELIVERY, or customer_collection_address when delivery_method is COLLECTION.

Responses

200Address updated successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

400Schema: error-response

The request was rejected. One of:

address is missing.
the fulfillment order is not open or allocated.
the fulfillment order or its order is on hold.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Order or fulfillment order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

patch/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderReference}/update-schedule

Update fulfillment order schedule

Replaces the delivery or collection window of a fulfillment order with the supplied scheduled_from and scheduled_to.

Preconditions. Neither the fulfillment order nor its order may be on hold. There is no status precondition.

What happens. The window is replaced and the FULFILLMENT_ORDER_UPDATE_SCHEDULE webhook fires.

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.
fulfillmentOrderReference	string	Yes	Carriyo `fulfillment_order_id` or your own `partner_fulfillment_order_reference`. The value is matched against `fulfillment_order_id` first, then `partner_fulfillment_order_reference`. A partner reference shared by more than one fulfillment order on the order returns 400. A value matching neither returns 404.

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.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

Content type: application/jsonSchema: update-fulfillment-order-schedule-requestrequired

scheduled_fromstringformat: date-time
Start of the scheduled window.
scheduled_tostringformat: date-time
End of the scheduled window.

Responses

200Schedule updated successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

400The fulfillment order or its order is on hold.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Order or fulfillment order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

patch/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderReference}/update-partner-references

Update fulfillment order partner references

Sets your references on a fulfillment order or on its individual fulfillments.

Preconditions. Neither the fulfillment order nor its order may be on hold, and the fulfillment order must have no active picks.

What to send. Send one of:

partner_fulfillment_order_reference, your reference for the fulfillment order.
fulfillments, a list of fulfillment_id and partner_fulfillment_reference pairs that set references on already fulfilled items.

When both are present only partner_fulfillment_order_reference is applied.

What happens. Nothing else on the fulfillment order changes. The FULFILLMENT_ORDER_UPDATE_PARTNER_FULFILLMENT_ORDER_REFERENCE webhook fires when the fulfillment order reference changed, and the FULFILLMENT_ORDER_UPDATE_PARTNER_FULFILLMENT_REFERENCES webhook when fulfillment references changed.

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.
fulfillmentOrderReference	string	Yes	Carriyo `fulfillment_order_id` or your own `partner_fulfillment_order_reference`. The value is matched against `fulfillment_order_id` first, then `partner_fulfillment_order_reference`. A partner reference shared by more than one fulfillment order on the order returns 400. A value matching neither returns 404.

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.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

Content type: application/jsonSchema: update-fulfillment-order-partner-references-requestrequired

partner_fulfillment_order_referencestring
Updated partner reference for the fulfillment order.
fulfillmentsupdate-fulfillment-request[]
Updates to existing fulfillments' partner references.

Responses

200Partner references updated successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

400Schema: error-response

The request was rejected. One of:

the fulfillment order has active picks.
the fulfillment order or its order is on hold.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Order or fulfillment order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

post/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderReference}/cancel

Cancel fulfillment order line items

Cancels selected line items of a fulfillment order.

Preconditions. Only items in open or allocated status qualify; unfulfill a fulfilled item first. Cancellation is allowed while the fulfillment order or its order is on hold.

What to send. line_items and cancellation_reason are both required. line_items names the items and quantities to cancel, and the reason is recorded on each. Identify each item by the order line item's id, or by product_id, product_ref or sku when that names exactly one line item on the fulfillment order.

What happens.

Each cancelled item's status becomes cancelled with the reason.
The fulfillment order's picks are cancelled when nothing is left to pick.
When every item is cancelled the fulfillment order becomes cancelled and its hold is released.
The order status is recalculated and the FULFILLMENT_ORDER_CANCEL_LINE_ITEMS webhook fires.

Inventory. With inventory management enabled and a fulfillment_location set on the fulfillment order, reserved is reduced by the cancelled quantity.

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.
fulfillmentOrderReference	string	Yes	Carriyo `fulfillment_order_id` or your own `partner_fulfillment_order_reference`. The value is matched against `fulfillment_order_id` first, then `partner_fulfillment_order_reference`. A partner reference shared by more than one fulfillment order on the order returns 400. A value matching neither returns 404.

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.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

Content type: application/jsonSchema: cancel-fo-line-items-requestrequired

cancellation_reasonstringrequired
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
line_itemsfo-line-item-ref[]required
The line items to cancel, each with its quantity.

Responses

200Line items cancelled successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

400Schema: error-response

The request was rejected. One of:

line_items is missing or empty.
cancellation_reason is missing.
an item carries neither id nor a product identifier.
a product identifier matches no line item on the fulfillment order, or matches more than one.
quantity is missing or below 1.
an item is fulfilled, closed or already cancelled.
a quantity exceeds what the item has.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Order or fulfillment order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

post/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderReference}/on-hold

Hold fulfillment order

Puts a single fulfillment order on hold without affecting the rest of the order.

Preconditions. The fulfillment order must be open or allocated and not already on hold, and its order must not be on hold.

What happens.

The fulfillment order status becomes on_hold; the order status is unchanged.
on_hold_details records the hold; an earlier hold moves into history.
While the hold is active, every operation on that fulfillment order except cancel and release returns 400.
The FULFILLMENT_ORDER_ON_HOLD webhook fires.

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.
fulfillmentOrderReference	string	Yes	Carriyo `fulfillment_order_id` or your own `partner_fulfillment_order_reference`. The value is matched against `fulfillment_order_id` first, then `partner_fulfillment_order_reference`. A partner reference shared by more than one fulfillment order on the order returns 400. A value matching neither returns 404.

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.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

Content type: application/jsonSchema: on-hold-request

assigned_toassigned-to
The user or team responsible for resolving a hold.
prioritystring
Priority of the hold for whoever works it.
Values:LOWNORMALHIGHURGENT
sla_hoursinteger
Hours allowed to resolve the hold. Carriyo stores the deadline as sla_timestamp.
notesstring
Why the hold was placed.

Responses

200Fulfillment order placed on hold successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

400Schema: error-response

The request was rejected. One of:

the fulfillment order is not open or allocated.
the fulfillment order is already on hold.
the order is on hold.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Order or fulfillment order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

post/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderReference}/release-on-hold

Release fulfillment order hold

Releases an active hold on a single fulfillment order and returns it to the status derived from its line items.

Preconditions. The fulfillment order must be on_hold and its order must not be on hold.

What happens.

The fulfillment order returns to open or allocated as derived from its line items.
on_hold_details is kept with the release details.
The FULFILLMENT_ORDER_RELEASE_ON_HOLD webhook fires.

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.
fulfillmentOrderReference	string	Yes	Carriyo `fulfillment_order_id` or your own `partner_fulfillment_order_reference`. The value is matched against `fulfillment_order_id` first, then `partner_fulfillment_order_reference`. A partner reference shared by more than one fulfillment order on the order returns 400. A value matching neither returns 404.

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.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

Content type: application/jsonSchema: release-on-hold-request

notesstring
Why the hold was released. Stored as release_notes.

Responses

200Hold released successfully.Schema: order

tenantstring
The tenant identifier.
order_idstring
Carriyo's unique identifier for the order.
merchantstring
The merchant identifier.
partner_order_referencestring
Your system's order reference.
languagestring
Language code for customer communications.
order_datestringformat: date-time
The date when the order was placed.
sales_channelstring
The sales channel where the order originated.
creation_sourcerequest-source
Describes which system or actor triggered an order create or update.
update_sourcerequest-source
Describes which system or actor triggered an order create or update.
statusstring
Current status of the order: - open - Order created, not yet allocated - partially_allocated - Some items allocated to fulfillment locations - allocated - All items allocated to fulfillment locations - on_hold - Order is held and cannot be updated or fulfilled until the hold is released - processing - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled) - fulfilled - All items have been fulfilled - cancelled - Order has been cancelled - closed - Order is complete and closed
Values:openpartially_allocatedallocatedon_holdprocessingfulfilledcancelledclosed
status_update_datestringformat: date-time
When status last changed.
key_milestonesobject
When the order first reached each of fulfilled, cancelled and closed, keyed by status.
cancellation_reasonstring
Why the order or its items were cancelled: customer_cancellation (the customer asked), auto_allocation_failed (no location could be allocated), inventory_out_of_stock, staff_error, payment_issue or other. Carriyo sets inventory_out_of_stock or auto_allocation_failed itself on items that allocation auto-cancels.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
on_hold_detailson-hold-details
The latest hold on the order, with its release recorded once it ends and earlier holds in history.
billing_addressaddress
Address used for customer, billing, delivery and customer-collection addresses. Pass the fields directly, or reference a configured location by partner_location_id, partner_location_name or partner_location_code.
customeraddress
The customer's contact and address details.
customer_keystring
A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
paymentorder-payment
redactedboolean
Whether personal data has been redacted.
taxes_includedboolean
Whether prices include taxes.
duties_includedboolean
Whether prices include duties.
discount_applicationsdiscount-application[]
line_itemsline-item[]
fulfillment_ordersfulfillment-order[]
shipping_linesshipping-line[]
error_detailserror-detail[]
Any errors that occurred during order processing.
custom_attributescustom-attributes
Custom attributes as a map of attribute name to a list of string values, limited to the attributes configured for your account.
creation_datestringformat: date-time
When the order was created in Carriyo.
update_datestringformat: date-time
When the order was last updated.

400Schema: error-response

The request was rejected. One of:

the fulfillment order is not on_hold.
the order is on hold; release the order instead.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Order or fulfillment order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

post/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderReference}/allocate

Allocate fulfillment order

Runs allocation for a single fulfillment order and, unless dry_run is true, applies the result to the order.

Preconditions. The fulfillment order must be open or allocated, neither it nor its order may be on hold, and its delivery_method must not be DIGITAL.

What to send. Two body flags decide whether a result is accepted:

allow_partial_order_allocation is read from the request only; omitted, partial results are accepted.
allow_order_splitting defaults to the order management setting of the same name; a value in the request overrides it.

What comes back. The response lists the proposed fulfillment orders: one per allocated location, plus one open fulfillment order holding any items that could not be allocated. committed says whether the result was applied.

When the result is applied. With dry_run false and the result accepted, committed is true and Carriyo:

gives the existing fulfillment order the first proposal, keeping its fulfillment_order_id;
creates a new fulfillment order for each further proposal;
moves inventory reservations to the allocated locations when inventory management is enabled;
recalculates the order status.

The FULFILLMENT_ORDER_ALLOCATE webhook fires only when the result is committed.

When nothing is saved. committed is false when dry_run is true or the result is rejected. A result is rejected when:

it contains no items;
items remain unallocated while allow_partial_order_allocation is false;
it spans more than one location while allow_order_splitting is false.

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.
fulfillmentOrderReference	string	Yes	Carriyo `fulfillment_order_id` or your own `partner_fulfillment_order_reference`. The value is matched against `fulfillment_order_id` first, then `partner_fulfillment_order_reference`. A partner reference shared by more than one fulfillment order on the order returns 400. A value matching neither returns 404.

Query parameters

Name	Type	Required	Description
dry_run	boolean	No	If true, returns the proposed allocation without saving anything.

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.

Header parameters

Name	Type	Required	Description
Idempotency-Key	string	No	Optional client-generated key that identifies one logical operation. Reuse the same key when retrying with the same payload. Replays the stored response. See https://carriyo.com/docs/api/idempotency/.

Request body

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

allow_order_splittingboolean
Whether items may be allocated across more than one location. Overrides your order management settings for this run.
allow_partial_order_allocationboolean
Whether a result that leaves some items unallocated is applied. When false, such a result is returned with committed set to false.
allocation_prioritiesallocation-priority[]
Ordered priorities for the allocation engine. Overrides your order management settings for this run.
reasonstring
Reason recorded in allocation_history. Defaults to Allocation.

Responses

200Allocation completed. Check committed to see whether it was applied.Schema: allocation-response

committedboolean
Whether the result was applied to the order. false for a dry run or a rejected result.
all_items_allocatedboolean
Whether every requested item was allocated to a location.
fulfillment_ordersfulfillment-order[]
The resulting fulfillment orders, one per allocated location plus one for any unallocated items. Proposals in an uncommitted response carry no fulfillment_order_id.
allocation_summarystring
Human-readable summary of each allocation pass.

400Schema: error-response

The request was rejected. One of:

the fulfillment order is not open or allocated.
the fulfillment order or its order is on hold.
its delivery_method is DIGITAL.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Order or fulfillment order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

get/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderReference}/available-locations

List available locations

Lists the fulfillment locations the allocation engine would evaluate for a fulfillment order, with stock availability per item. Nothing is saved.

Behavior. Locations are sorted by availability (AVAILABLE, then PARTIALLY_AVAILABLE, then UNAVAILABLE), then by how many requested items they can supply, then by location_code. current marks the location currently assigned to the fulfillment order.

Path parameters

Name	Type	Required	Description
orderReference	string	Yes	Carriyo `order_id` or your own `partner_order_reference`. The value is matched against `order_id` first, then `partner_order_reference`; if neither matches, the response is 404.
fulfillmentOrderReference	string	Yes	Carriyo `fulfillment_order_id` or your own `partner_fulfillment_order_reference`. The value is matched against `fulfillment_order_id` first, then `partner_fulfillment_order_reference`. A partner reference shared by more than one fulfillment order on the order returns 400. A value matching neither returns 404.

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

200Available locations evaluated successfully.Schema: available-locations-response

order_referencestring
Carriyo order_id of the order.
fulfillment_order_idstring
Carriyo identifier of the fulfillment order.
current_location_idstring
Partner location ID currently assigned to the fulfillment order, if any.
requested_itemsrequested-item[]
The fulfillment order's items and requested quantities.
locationsavailable-location[]
Candidate locations, best first.
evaluation_summarystring
Human-readable count of locations evaluated by availability.

400Schema: error-response

The request was rejected. One of:

the fulfillment order has active picks.
the fulfillment order has no line items.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404Order or fulfillment order not found.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

Order Allocation Rules

Rules that decide how an order is split into fulfillment orders across your fulfillment locations, evaluated in sequence.

6 operations · 0 objects

post/order-allocation-rules

Create order allocation rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Creates an order allocation rule.

Behavior. A new rule takes the sequence you send; nothing appends it last, and a lower sequence pre-empts existing rules because the lowest matched sequence wins. Duplicate sequences are not rejected; a duplicate name is.

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

201Created.

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

get/order-allocation-rules

List order allocation rules

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Lists the order allocation rules configured for the merchant, ordered by evaluation priority (sequence).

Headers

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

Responses

200Success.

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

get/order-allocation-rules/{rule_id}

Get order allocation rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Returns a single order allocation rule by its rule_id.

Path parameters

Name	Type	Required	Description
rule_id	string	Yes	Allocation 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

200Success.

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

put/order-allocation-rules/{rule_id}

Update order allocation rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Replaces an order allocation rule.

Behavior. The request body fully replaces the existing rule; fields you omit are reset to defaults. The rule's evaluation priority is managed separately with Update rule sequence.

Path parameters

Name	Type	Required	Description
rule_id	string	Yes	Allocation 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/jsonrequired

Responses

200Success.

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

delete/order-allocation-rules/{rule_id}

Delete order allocation rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Deletes an order allocation rule.

Behavior. Orders that would have matched this rule fall through to the next matching rule in evaluation order.

Path parameters

Name	Type	Required	Description
rule_id	string	Yes	Allocation 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

200Deleted.

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

patch/order-allocation-rules/sequences

Update rule sequence

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Sets the priority order in which allocation rules are evaluated.

Behavior. Send only the rules to move; rules not in the body are untouched.

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

An array. Each item has the following fields:

ruleIdstring
sequenceinteger

Responses

200Updated.

400None of the rule ids resolve.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

Order Hold Rules

Rules that put a new order on hold automatically when it matches their conditions, so someone can review it before it is fulfilled.

8 operations · 0 objects

post/order-hold-rules

Create order hold rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Creates an order hold rule.

What to send. rule_name, the conditions to match, and the hold_action to stamp on the hold. status defaults to ACTIVE and match_type to ALL. rule_id, rule_set_id, updated_by_user and the dates are assigned by Carriyo; values you send for them are ignored.

Sequence. A rule sent without sequence, or with 0, is placed after the highest sequence in use. Duplicate sequences are not rejected.

What happens. An ACTIVE rule applies to orders created from then on. A rule with no conditions never matches an 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`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: order-hold-rulerequired

rule_idstring
Carriyo-issued identifier for the rule.
rule_set_idstring
Rule set the rule belongs to. A tenant has one, created with its first rule.
rule_namestringrequired
Name of the rule. Unique within the tenant.
sequenceinteger
Evaluation order. Rules are evaluated in ascending sequence, and the first ACTIVE rule that matches places the hold.
statusstring
Only ACTIVE rules are evaluated.
Values:ACTIVEINACTIVE
match_typestring
How the conditions combine. ALL needs every condition the rule sets to match; ANY needs at least one.
Values:ALLANY
order_valueorder-value-condition[]
Order value ranges, one per currency. Only the entry for the order's currency is evaluated; an order in a currency with no entry does not match.
payment_methodstring-condition
Match the order's payment method, CASH_ON_DELIVERY or PREPAID.
destinationgeography-condition
Match the delivery country, state, city or area.
item_quantityinteger-range-condition
Match the total quantity across the order's line items.
item_categoriesstring-condition
Match the categories of the order's line items. INCLUSION matches when at least one item is in a listed category; EXCLUSION matches when none is.
discount_percentnumber-range-condition
Match the discount on the order, as a percentage.
sales_channelsstring-condition
Match the order's sales channel.
merchantsstring-condition
Match the order's merchant.
address_mismatchboolean
Match on whether the billing address differs from the customer address.
customer_verifiedboolean
Match on whether the customer is verified. A customer whose verification is unknown counts as not verified.
custom_conditions_v2custom-attribute-condition[]
Match the order's custom attributes.
hold_actionhold-action
What to record on the hold when the rule matches.
updated_by_userstring
User who last changed the rule, or SYSTEM for a change made with an API client.
creation_datestringformat: date-time
When the rule was created.
update_datestringformat: date-time
When the rule was last changed.

Responses

201Order hold rule created.Schema: order-hold-rule

rule_idstring
Carriyo-issued identifier for the rule.
rule_set_idstring
Rule set the rule belongs to. A tenant has one, created with its first rule.
rule_namestringrequired
Name of the rule. Unique within the tenant.
sequenceinteger
Evaluation order. Rules are evaluated in ascending sequence, and the first ACTIVE rule that matches places the hold.
statusstring
Only ACTIVE rules are evaluated.
Values:ACTIVEINACTIVE
match_typestring
How the conditions combine. ALL needs every condition the rule sets to match; ANY needs at least one.
Values:ALLANY
order_valueorder-value-condition[]
Order value ranges, one per currency. Only the entry for the order's currency is evaluated; an order in a currency with no entry does not match.
payment_methodstring-condition
Match the order's payment method, CASH_ON_DELIVERY or PREPAID.
destinationgeography-condition
Match the delivery country, state, city or area.
item_quantityinteger-range-condition
Match the total quantity across the order's line items.
item_categoriesstring-condition
Match the categories of the order's line items. INCLUSION matches when at least one item is in a listed category; EXCLUSION matches when none is.
discount_percentnumber-range-condition
Match the discount on the order, as a percentage.
sales_channelsstring-condition
Match the order's sales channel.
merchantsstring-condition
Match the order's merchant.
address_mismatchboolean
Match on whether the billing address differs from the customer address.
customer_verifiedboolean
Match on whether the customer is verified. A customer whose verification is unknown counts as not verified.
custom_conditions_v2custom-attribute-condition[]
Match the order's custom attributes.
hold_actionhold-action
What to record on the hold when the rule matches.
updated_by_userstring
User who last changed the rule, or SYSTEM for a change made with an API client.
creation_datestringformat: date-time
When the rule was created.
update_datestringformat: date-time
When the rule was last changed.

400Schema: error-response

The request was rejected. One of:

rule_name is missing.
another order hold rule already uses this rule_name.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

get/order-hold-rules

List order hold rules

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Lists the tenant's order hold rules, whatever their status. The list is not sorted; order the rules by sequence to get the evaluation 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

200The tenant's order hold rules. Empty when there are none.

An array of order-hold-rule. Each item has the following fields:

rule_idstring
Carriyo-issued identifier for the rule.
rule_set_idstring
Rule set the rule belongs to. A tenant has one, created with its first rule.
rule_namestringrequired
Name of the rule. Unique within the tenant.
sequenceinteger
Evaluation order. Rules are evaluated in ascending sequence, and the first ACTIVE rule that matches places the hold.
statusstring
Only ACTIVE rules are evaluated.
Values:ACTIVEINACTIVE
match_typestring
How the conditions combine. ALL needs every condition the rule sets to match; ANY needs at least one.
Values:ALLANY
order_valueorder-value-condition[]
Order value ranges, one per currency. Only the entry for the order's currency is evaluated; an order in a currency with no entry does not match.
payment_methodstring-condition
Match the order's payment method, CASH_ON_DELIVERY or PREPAID.
destinationgeography-condition
Match the delivery country, state, city or area.
item_quantityinteger-range-condition
Match the total quantity across the order's line items.
item_categoriesstring-condition
Match the categories of the order's line items. INCLUSION matches when at least one item is in a listed category; EXCLUSION matches when none is.
discount_percentnumber-range-condition
Match the discount on the order, as a percentage.
sales_channelsstring-condition
Match the order's sales channel.
merchantsstring-condition
Match the order's merchant.
address_mismatchboolean
Match on whether the billing address differs from the customer address.
customer_verifiedboolean
Match on whether the customer is verified. A customer whose verification is unknown counts as not verified.
custom_conditions_v2custom-attribute-condition[]
Match the order's custom attributes.
hold_actionhold-action
What to record on the hold when the rule matches.
updated_by_userstring
User who last changed the rule, or SYSTEM for a change made with an API client.
creation_datestringformat: date-time
When the rule was created.
update_datestringformat: date-time
When the rule was last changed.

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

get/order-hold-rules/activity

List order hold rule activity

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Lists the changes made to the tenant's order hold rules: rules created and updated, status changes and sequence changes, each with who made it and which fields changed.

What is covered. Only rules that still exist. When a rule is deleted, its entries leave the list.

Query parameters

Name	Type	Required	Description
rule_set_id	string	No	Rule set to read activity for. Defaults to the tenant's rule set.
page_num	integer	No	Page to return, starting at `1`. Default `1`; a value below `1` is treated as `1`.
rows_per_page	integer	No	Entries per page. Default `20`; a value above `100` is treated as `100`.
sort	string	No	Order by time. Default `desc`, newest first; any value other than `asc` is treated as `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

200A page of activity entries.Schema: order-hold-rule-activity-response

itemsorder-hold-rule-activity-entry[]
The activity entries for the requested page.
totalinteger
Total entries across all pages.
page_numinteger
The page returned.
rows_per_pageinteger
Entries per page used for this response.
truncatedboolean
True when the rule set has more than 1000 entries and the list was cut off there.

404No rule set with this rule_set_id exists.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

patch/order-hold-rules/sequences

Update order hold rule sequence

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Sets the order in which order hold rules are evaluated. Rules are evaluated in ascending sequence, and the first ACTIVE rule that matches places the hold.

What to send. One entry per rule to move. Rules you leave out keep their sequence, and an entry whose rule_id does not exist is ignored as long as at least one other entry resolves. Duplicate sequences are not rejected.

Activity. Mark the rule the user moved with primary: true. Its change is recorded as a sequence update; the other entries are recorded as realignments.

Headers

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

Request body

Content type: application/jsonSchema: order-hold-rule-sequences-requestrequired

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

rule_idstringrequired
Rule to move.
sequenceintegerrequired
Sequence the rule should take.
primaryboolean
True for the rule the user moved, as opposed to a rule shifted to make room.

Responses

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

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

rule_idstringrequired
Rule to move.
sequenceintegerrequired
Sequence the rule should take.
primaryboolean
True for the rule the user moved, as opposed to a rule shifted to make room.

400None of the rule_id values belong to a rule of the tenant, or the body is an empty array.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

get/order-hold-rules/{rule_id}

Get order hold rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Returns a single order hold rule by its rule_id.

Path parameters

Name	Type	Required	Description
rule_id	string	Yes	Order hold 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 order hold rule.Schema: order-hold-rule

rule_idstring
Carriyo-issued identifier for the rule.
rule_set_idstring
Rule set the rule belongs to. A tenant has one, created with its first rule.
rule_namestringrequired
Name of the rule. Unique within the tenant.
sequenceinteger
Evaluation order. Rules are evaluated in ascending sequence, and the first ACTIVE rule that matches places the hold.
statusstring
Only ACTIVE rules are evaluated.
Values:ACTIVEINACTIVE
match_typestring
How the conditions combine. ALL needs every condition the rule sets to match; ANY needs at least one.
Values:ALLANY
order_valueorder-value-condition[]
Order value ranges, one per currency. Only the entry for the order's currency is evaluated; an order in a currency with no entry does not match.
payment_methodstring-condition
Match the order's payment method, CASH_ON_DELIVERY or PREPAID.
destinationgeography-condition
Match the delivery country, state, city or area.
item_quantityinteger-range-condition
Match the total quantity across the order's line items.
item_categoriesstring-condition
Match the categories of the order's line items. INCLUSION matches when at least one item is in a listed category; EXCLUSION matches when none is.
discount_percentnumber-range-condition
Match the discount on the order, as a percentage.
sales_channelsstring-condition
Match the order's sales channel.
merchantsstring-condition
Match the order's merchant.
address_mismatchboolean
Match on whether the billing address differs from the customer address.
customer_verifiedboolean
Match on whether the customer is verified. A customer whose verification is unknown counts as not verified.
custom_conditions_v2custom-attribute-condition[]
Match the order's custom attributes.
hold_actionhold-action
What to record on the hold when the rule matches.
updated_by_userstring
User who last changed the rule, or SYSTEM for a change made with an API client.
creation_datestringformat: date-time
When the rule was created.
update_datestringformat: date-time
When the rule was last changed.

404No order hold rule with this rule_id exists.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

put/order-hold-rules/{rule_id}

Update order hold rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Replaces an order hold rule.

What to send. The full rule. The body replaces every condition and the hold_action; whatever you omit is removed. An omitted status becomes ACTIVE and an omitted match_type becomes ALL.

Sequence. Send the rule's current sequence. An omitted sequence is stored as 0, which moves the rule ahead of every other rule.

What is kept. rule_id, rule_set_id and creation_date.

Path parameters

Name	Type	Required	Description
rule_id	string	Yes	Order hold 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: order-hold-rulerequired

rule_idstring
Carriyo-issued identifier for the rule.
rule_set_idstring
Rule set the rule belongs to. A tenant has one, created with its first rule.
rule_namestringrequired
Name of the rule. Unique within the tenant.
sequenceinteger
Evaluation order. Rules are evaluated in ascending sequence, and the first ACTIVE rule that matches places the hold.
statusstring
Only ACTIVE rules are evaluated.
Values:ACTIVEINACTIVE
match_typestring
How the conditions combine. ALL needs every condition the rule sets to match; ANY needs at least one.
Values:ALLANY
order_valueorder-value-condition[]
Order value ranges, one per currency. Only the entry for the order's currency is evaluated; an order in a currency with no entry does not match.
payment_methodstring-condition
Match the order's payment method, CASH_ON_DELIVERY or PREPAID.
destinationgeography-condition
Match the delivery country, state, city or area.
item_quantityinteger-range-condition
Match the total quantity across the order's line items.
item_categoriesstring-condition
Match the categories of the order's line items. INCLUSION matches when at least one item is in a listed category; EXCLUSION matches when none is.
discount_percentnumber-range-condition
Match the discount on the order, as a percentage.
sales_channelsstring-condition
Match the order's sales channel.
merchantsstring-condition
Match the order's merchant.
address_mismatchboolean
Match on whether the billing address differs from the customer address.
customer_verifiedboolean
Match on whether the customer is verified. A customer whose verification is unknown counts as not verified.
custom_conditions_v2custom-attribute-condition[]
Match the order's custom attributes.
hold_actionhold-action
What to record on the hold when the rule matches.
updated_by_userstring
User who last changed the rule, or SYSTEM for a change made with an API client.
creation_datestringformat: date-time
When the rule was created.
update_datestringformat: date-time
When the rule was last changed.

Responses

200Order hold rule replaced.Schema: order-hold-rule

rule_idstring
Carriyo-issued identifier for the rule.
rule_set_idstring
Rule set the rule belongs to. A tenant has one, created with its first rule.
rule_namestringrequired
Name of the rule. Unique within the tenant.
sequenceinteger
Evaluation order. Rules are evaluated in ascending sequence, and the first ACTIVE rule that matches places the hold.
statusstring
Only ACTIVE rules are evaluated.
Values:ACTIVEINACTIVE
match_typestring
How the conditions combine. ALL needs every condition the rule sets to match; ANY needs at least one.
Values:ALLANY
order_valueorder-value-condition[]
Order value ranges, one per currency. Only the entry for the order's currency is evaluated; an order in a currency with no entry does not match.
payment_methodstring-condition
Match the order's payment method, CASH_ON_DELIVERY or PREPAID.
destinationgeography-condition
Match the delivery country, state, city or area.
item_quantityinteger-range-condition
Match the total quantity across the order's line items.
item_categoriesstring-condition
Match the categories of the order's line items. INCLUSION matches when at least one item is in a listed category; EXCLUSION matches when none is.
discount_percentnumber-range-condition
Match the discount on the order, as a percentage.
sales_channelsstring-condition
Match the order's sales channel.
merchantsstring-condition
Match the order's merchant.
address_mismatchboolean
Match on whether the billing address differs from the customer address.
customer_verifiedboolean
Match on whether the customer is verified. A customer whose verification is unknown counts as not verified.
custom_conditions_v2custom-attribute-condition[]
Match the order's custom attributes.
hold_actionhold-action
What to record on the hold when the rule matches.
updated_by_userstring
User who last changed the rule, or SYSTEM for a change made with an API client.
creation_datestringformat: date-time
When the rule was created.
update_datestringformat: date-time
When the rule was last changed.

400Schema: error-response

The request was rejected. One of:

rule_name is missing.
another order hold rule already uses this rule_name.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404No order hold rule with this rule_id exists.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

delete/order-hold-rules/{rule_id}

Delete order hold rule

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Permanently deletes an order hold rule. Its entries are also removed from the rule activity.

Path parameters

Name	Type	Required	Description
rule_id	string	Yes	Order hold 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

200Order hold rule deleted. Response body is empty.

404No order hold rule with this rule_id exists.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

patch/order-hold-rules/{rule_id}/update-status

Update order hold rule status

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Changes the status of an order hold rule without sending the rest of the rule. Set INACTIVE to stop the rule being evaluated and ACTIVE to resume it.

Path parameters

Name	Type	Required	Description
rule_id	string	Yes	Order hold 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: order-hold-rule-status-requestrequired

statusstringrequired
Status to set. It must differ from the rule's current status.
Values:ACTIVEINACTIVE

Responses

200Status changed. Returns the rule.Schema: order-hold-rule

rule_idstring
Carriyo-issued identifier for the rule.
rule_set_idstring
Rule set the rule belongs to. A tenant has one, created with its first rule.
rule_namestringrequired
Name of the rule. Unique within the tenant.
sequenceinteger
Evaluation order. Rules are evaluated in ascending sequence, and the first ACTIVE rule that matches places the hold.
statusstring
Only ACTIVE rules are evaluated.
Values:ACTIVEINACTIVE
match_typestring
How the conditions combine. ALL needs every condition the rule sets to match; ANY needs at least one.
Values:ALLANY
order_valueorder-value-condition[]
Order value ranges, one per currency. Only the entry for the order's currency is evaluated; an order in a currency with no entry does not match.
payment_methodstring-condition
Match the order's payment method, CASH_ON_DELIVERY or PREPAID.
destinationgeography-condition
Match the delivery country, state, city or area.
item_quantityinteger-range-condition
Match the total quantity across the order's line items.
item_categoriesstring-condition
Match the categories of the order's line items. INCLUSION matches when at least one item is in a listed category; EXCLUSION matches when none is.
discount_percentnumber-range-condition
Match the discount on the order, as a percentage.
sales_channelsstring-condition
Match the order's sales channel.
merchantsstring-condition
Match the order's merchant.
address_mismatchboolean
Match on whether the billing address differs from the customer address.
customer_verifiedboolean
Match on whether the customer is verified. A customer whose verification is unknown counts as not verified.
custom_conditions_v2custom-attribute-condition[]
Match the order's custom attributes.
hold_actionhold-action
What to record on the hold when the rule matches.
updated_by_userstring
User who last changed the rule, or SYSTEM for a change made with an API client.
creation_datestringformat: date-time
When the rule was created.
update_datestringformat: date-time
When the rule was last changed.

400Schema: error-response

The request was rejected. One of:

status is missing.
the rule already has this status.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

404No order hold rule with this rule_id exists.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

Order Management Settings

The tenant-wide settings that switch automatic allocation and inventory management on, and set how orders are split, when stock moves, and when uncollected orders expire. A tenant has one settings record.

4 operations · 0 objects

post/order-management-settings

Create order management settings

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Creates the tenant's order management settings. A tenant has one settings record, so this call works only while none exists.

What to send. Every field is optional, and nothing is defaulted: a field you omit is stored unset. Send the full set of settings.

What happens. Automatic allocation is off until a record exists with enable_automatic_order_allocation set to true; until then every order is created in open.

Headers

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

Request body

Content type: application/jsonSchema: order-management-settingsrequired

tenantstring
Tenant the settings belong to.
enable_automatic_order_allocationboolean
When true, the allocation engine allocates orders at creation. Unset or false, every order is created in open.
allow_order_splittingboolean
Whether allocation may split an order across more than one location. An allocate request can override it.
allow_partial_order_allocationboolean
Whether an order may be allocated when some of its items cannot be supplied.
allocation_prioritiesallocation-priority[]
The order in which the allocation engine ranks candidate locations. Each entry needs a sequence of 1 or more and an allocation_priority_type.
enable_inventory_managementboolean
When true, order and shipment events move stock.
stock_reduction_timingstring
The event that reduces stock for an outbound order.
Values:ON_SHIPMENT_SHIPPEDON_ORDER_FULFILLED
stock_increase_timingstring
The event that adds returned stock back.
Values:ON_SHIPMENT_DELIVEREDON_RETURN_RECEIVED
customer_collection_auto_expire_enabledboolean
When true, a collection left in ready_to_collect moves to expired after customer_collection_auto_expire_days.
customer_collection_auto_expire_daysinteger
Days a collection may wait in ready_to_collect before it expires.
customer_collection_auto_cancel_enabledboolean
When true, an expired collection moves to cancelled after customer_collection_auto_cancel_days. It has no effect unless auto-expire is also on.
customer_collection_auto_cancel_daysinteger
Days an expired collection waits before it is cancelled.
creation_datestringformat: date-time
When the settings record was created.
update_datestringformat: date-time
When the settings were last changed.
creation_sourcerequest-source
Who created the settings record.
update_sourcerequest-source
Who last changed the settings.

Responses

200Order management settings created.Schema: order-management-settings

tenantstring
Tenant the settings belong to.
enable_automatic_order_allocationboolean
When true, the allocation engine allocates orders at creation. Unset or false, every order is created in open.
allow_order_splittingboolean
Whether allocation may split an order across more than one location. An allocate request can override it.
allow_partial_order_allocationboolean
Whether an order may be allocated when some of its items cannot be supplied.
allocation_prioritiesallocation-priority[]
The order in which the allocation engine ranks candidate locations. Each entry needs a sequence of 1 or more and an allocation_priority_type.
enable_inventory_managementboolean
When true, order and shipment events move stock.
stock_reduction_timingstring
The event that reduces stock for an outbound order.
Values:ON_SHIPMENT_SHIPPEDON_ORDER_FULFILLED
stock_increase_timingstring
The event that adds returned stock back.
Values:ON_SHIPMENT_DELIVEREDON_RETURN_RECEIVED
customer_collection_auto_expire_enabledboolean
When true, a collection left in ready_to_collect moves to expired after customer_collection_auto_expire_days.
customer_collection_auto_expire_daysinteger
Days a collection may wait in ready_to_collect before it expires.
customer_collection_auto_cancel_enabledboolean
When true, an expired collection moves to cancelled after customer_collection_auto_cancel_days. It has no effect unless auto-expire is also on.
customer_collection_auto_cancel_daysinteger
Days an expired collection waits before it is cancelled.
creation_datestringformat: date-time
When the settings record was created.
update_datestringformat: date-time
When the settings were last changed.
creation_sourcerequest-source
Who created the settings record.
update_sourcerequest-source
Who last changed the settings.

400Schema: error-response

The request was rejected. One of:

the tenant already has order management settings.
an allocation_priorities entry has no allocation_priority_type, or has no sequence or one below 1.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

get/order-management-settings

Get order management settings

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Returns the tenant's order management settings.

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 tenant's order management settings.Schema: order-management-settings

tenantstring
Tenant the settings belong to.
enable_automatic_order_allocationboolean
When true, the allocation engine allocates orders at creation. Unset or false, every order is created in open.
allow_order_splittingboolean
Whether allocation may split an order across more than one location. An allocate request can override it.
allow_partial_order_allocationboolean
Whether an order may be allocated when some of its items cannot be supplied.
allocation_prioritiesallocation-priority[]
The order in which the allocation engine ranks candidate locations. Each entry needs a sequence of 1 or more and an allocation_priority_type.
enable_inventory_managementboolean
When true, order and shipment events move stock.
stock_reduction_timingstring
The event that reduces stock for an outbound order.
Values:ON_SHIPMENT_SHIPPEDON_ORDER_FULFILLED
stock_increase_timingstring
The event that adds returned stock back.
Values:ON_SHIPMENT_DELIVEREDON_RETURN_RECEIVED
customer_collection_auto_expire_enabledboolean
When true, a collection left in ready_to_collect moves to expired after customer_collection_auto_expire_days.
customer_collection_auto_expire_daysinteger
Days a collection may wait in ready_to_collect before it expires.
customer_collection_auto_cancel_enabledboolean
When true, an expired collection moves to cancelled after customer_collection_auto_cancel_days. It has no effect unless auto-expire is also on.
customer_collection_auto_cancel_daysinteger
Days an expired collection waits before it is cancelled.
creation_datestringformat: date-time
When the settings record was created.
update_datestringformat: date-time
When the settings were last changed.
creation_sourcerequest-source
Who created the settings record.
update_sourcerequest-source
Who last changed the settings.

404The tenant has no order management settings. Response body is empty.

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

put/order-management-settings

Update order management settings

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Replaces the tenant's order management settings.

What to send. The full settings. The body replaces every setting, and a field you omit comes back as null. That applies to enable_automatic_order_allocation, enable_inventory_management, stock_reduction_timing, stock_increase_timing and allocation_priorities as much as to the rest.

What is kept. creation_date and creation_source stay as they were. update_date and update_source are set from this call.

Headers

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

Request body

Content type: application/jsonSchema: order-management-settingsrequired

tenantstring
Tenant the settings belong to.
enable_automatic_order_allocationboolean
When true, the allocation engine allocates orders at creation. Unset or false, every order is created in open.
allow_order_splittingboolean
Whether allocation may split an order across more than one location. An allocate request can override it.
allow_partial_order_allocationboolean
Whether an order may be allocated when some of its items cannot be supplied.
allocation_prioritiesallocation-priority[]
The order in which the allocation engine ranks candidate locations. Each entry needs a sequence of 1 or more and an allocation_priority_type.
enable_inventory_managementboolean
When true, order and shipment events move stock.
stock_reduction_timingstring
The event that reduces stock for an outbound order.
Values:ON_SHIPMENT_SHIPPEDON_ORDER_FULFILLED
stock_increase_timingstring
The event that adds returned stock back.
Values:ON_SHIPMENT_DELIVEREDON_RETURN_RECEIVED
customer_collection_auto_expire_enabledboolean
When true, a collection left in ready_to_collect moves to expired after customer_collection_auto_expire_days.
customer_collection_auto_expire_daysinteger
Days a collection may wait in ready_to_collect before it expires.
customer_collection_auto_cancel_enabledboolean
When true, an expired collection moves to cancelled after customer_collection_auto_cancel_days. It has no effect unless auto-expire is also on.
customer_collection_auto_cancel_daysinteger
Days an expired collection waits before it is cancelled.
creation_datestringformat: date-time
When the settings record was created.
update_datestringformat: date-time
When the settings were last changed.
creation_sourcerequest-source
Who created the settings record.
update_sourcerequest-source
Who last changed the settings.

Responses

200Order management settings replaced.Schema: order-management-settings

tenantstring
Tenant the settings belong to.
enable_automatic_order_allocationboolean
When true, the allocation engine allocates orders at creation. Unset or false, every order is created in open.
allow_order_splittingboolean
Whether allocation may split an order across more than one location. An allocate request can override it.
allow_partial_order_allocationboolean
Whether an order may be allocated when some of its items cannot be supplied.
allocation_prioritiesallocation-priority[]
The order in which the allocation engine ranks candidate locations. Each entry needs a sequence of 1 or more and an allocation_priority_type.
enable_inventory_managementboolean
When true, order and shipment events move stock.
stock_reduction_timingstring
The event that reduces stock for an outbound order.
Values:ON_SHIPMENT_SHIPPEDON_ORDER_FULFILLED
stock_increase_timingstring
The event that adds returned stock back.
Values:ON_SHIPMENT_DELIVEREDON_RETURN_RECEIVED
customer_collection_auto_expire_enabledboolean
When true, a collection left in ready_to_collect moves to expired after customer_collection_auto_expire_days.
customer_collection_auto_expire_daysinteger
Days a collection may wait in ready_to_collect before it expires.
customer_collection_auto_cancel_enabledboolean
When true, an expired collection moves to cancelled after customer_collection_auto_cancel_days. It has no effect unless auto-expire is also on.
customer_collection_auto_cancel_daysinteger
Days an expired collection waits before it is cancelled.
creation_datestringformat: date-time
When the settings record was created.
update_datestringformat: date-time
When the settings were last changed.
creation_sourcerequest-source
Who created the settings record.
update_sourcerequest-source
Who last changed the settings.

400Schema: error-response

The request was rejected. One of:

the tenant has no order management settings.
an allocation_priorities entry has no allocation_priority_type, or has no sequence or one below 1.

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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

delete/order-management-settings

Delete order management settings

Setup endpoint

Manage this in the Carriyo Dashboard, not the API.

Deletes the tenant's order management settings.

What happens. The record is removed, and Get order management settings answers 404 until settings are created again. Settings created afterwards are a new record with a new creation_date.

Headers

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

Responses

200Order management settings deleted. Response body is empty.

400The tenant has no order management settings.Schema: error-response

errorsstring[]
Error messages describing what went wrong.
error_detailserror-detail[]
Structured detail for each error, when available.
statusstring
HTTP status code of the response, as a string.

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>