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

Behavior

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.

Errors

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

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 [Idempotency](/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.
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.

400Invalid request payload.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

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.

Errors

429 — the monthly order-list quota is exhausted; the message states the limit.

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.

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

Behavior

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.

Errors

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

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 [Idempotency](/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.
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.

400Invalid request or order cannot be updated in current status.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}/cancel

Cancel order

Cancels an order and every fulfillment order on it.

Behavior

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.

Errors

400 — the order is already cancelled.

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 [Idempotency](/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.
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.
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.

400Order cannot be 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.

Behavior

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 [Idempotency](/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.
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.

Behavior

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.

Errors

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

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 [Idempotency](/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.
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.

400Order cannot be put 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}/release-on-hold

Release order hold

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

Behavior

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.

Errors

400 — the order is not on_hold.

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 [Idempotency](/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.
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.

400Order 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.

Behavior

Preconditions. Neither the order nor any of its fulfillment orders may be on hold, and at least one item must be pending. Pending covers open, allocated, pick_in_progress, picked and pack_in_progress.

Items in a pick or pack. Pending pick_in_progress and pack_in_progress items are fulfilled too, but the pick or pack that holds them stays open. Completing that pick later skips those items, and completing that pack fails with 400 and leaves the pack completed.

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 ORDER_FULFILL webhook fires.

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, the order total and the amount to collect on delivery are split across the shipments:

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

The last shipment takes the rounding remainder. 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.

Errors

400 — the order or any of its fulfillment orders is on hold.
400 — nothing is pending.

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 [Idempotency](/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.
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.

400Order has no items to fulfill, the order is on hold, or one of its fulfillment orders 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 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.

Behavior

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

Errors

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

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 [Idempotency](/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.
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.

400Order has no fulfillments to unfulfill, the order is on hold, or it came from Mirakl Connect.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/bulk/import

Bulk import orders

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

Behavior

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.

Errors

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

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 [Idempotency](/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.

400Invalid request payload.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 →

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.

Behavior

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.

Items in a pick or pack. A pick_in_progress or pack_in_progress item can be fulfilled, but the pick or pack that holds it stays open. Completing that pick later skips the item, and completing that pack fails with 400 and leaves the pack completed.

What to send

line_items names the items by id, each with a quantity no greater than the quantity still pending. Omit it, or send no body, to fulfill every pending item at its full quantity, including items in a pick or pack. 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.

When items close

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.

Errors

400 — line_items is empty.
400 — line_items is omitted and nothing on the fulfillment order is pending.
400 — an item is not in a pending status.
400 — a quantity exceeds what is pending.
400 — the fulfillment order or its order is on hold.

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 [Idempotency](/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-request[]
The line items to fulfill, by id and 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.
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.

400Invalid request or fulfillment not possible.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 →

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

Unfulfill fulfillment order

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

Behavior

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 lists the fulfillments to reverse. Each must belong to the fulfillment order. 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.

Errors

400 — a fulfillment id does not exist on the fulfillment order.
400 — the fulfillment order or its order is on hold.
400 — the order came from the Mirakl Connect connector.

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 [Idempotency](/api/idempotency/).

Request body

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

fulfillment_idsstring[]
List of fulfillment IDs to reverse.
partner_fulfillment_order_referencestring
Partner reference to identify the fulfillment to reverse.

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

400Cannot unfulfill - items may already be shipped.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 →

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

Merge fulfillment orders

Moves line items from one fulfillment order into another.

Behavior

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

Errors

400 — the source or destination contains fulfilled items.
400 — the source or destination has active picks.
400 — the source or destination, or the order, is on hold.
400 — the two differ in fulfillment_location, delivery_type, delivery method or delivery_option.

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 [Idempotency](/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.
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.

400Cannot merge fulfillment orders.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 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.

Behavior

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.

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.

Errors

400 — an item is fulfilled, cancelled or closed.
400 — a quantity exceeds what the item has.
400 — the fulfillment order or its order is on hold.
400 — the fulfillment order has active picks.

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 [Idempotency](/api/idempotency/).

Request body

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

line_itemsfo-line-item-request[]required
Line items to move to the new fulfillment order.
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.
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.

400Cannot split fulfillment order.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 →

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

Ship fulfillment order

Creates a shipment for selected items of a fulfillment order.

Behavior

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 names the items and quantities to ship; their status does not change. 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.

Errors

400 — an item is open, cancelled or closed.
400 — a quantity exceeds what is available.
400 — the fulfillment order has no delivery or collection address.
400 — the fulfillment order or its order is on hold.

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 [Idempotency](/api/idempotency/).

Request body

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

line_itemsfo-line-item-request[]
Specific fulfilled items to ship. Omit to ship all fulfilled items.
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.
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.

400Cannot create shipment.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-location

Update fulfillment order location

Reassigns a fulfillment order to a different location.

Behavior

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.

Errors

400 — the fulfillment order has active picks.
400 — the fulfillment order or its order is on hold.
400 — no location is assigned and none is supplied.
404 — the location cannot be resolved.

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 [Idempotency](/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.
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.

400Cannot update location.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-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.

Behavior

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.

Errors

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

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 [Idempotency](/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.
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.

400Invalid request.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-address

Update fulfillment order address

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

Behavior

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.

Errors

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

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 [Idempotency](/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.
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.

400Invalid request.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-schedule

Update fulfillment order schedule

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

Behavior

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.

Errors

400 — the fulfillment order or its order is on hold.

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 [Idempotency](/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.
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.

400Invalid request.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.

Behavior

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.

Errors

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

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 [Idempotency](/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.
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.

400Invalid request.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 →

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

Cancel fulfillment order line items

Cancels selected line items of a fulfillment order.

Behavior

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 names the items and quantities to cancel, and cancellation_reason is recorded on each.

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.

Errors

400 — an item is fulfilled, closed or already cancelled.
400 — a quantity exceeds what the item has.

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 [Idempotency](/api/idempotency/).

Request body

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

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.
Values:customer_cancellationauto_allocation_failedinventory_out_of_stockstaff_errorpayment_issueother
line_itemsfo-line-item-request[]required
The line items to cancel.

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

400Cannot cancel line items.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 →

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.

Behavior

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.

Errors

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

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

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 [Idempotency](/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.
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.

400Order or fulfillment order not found, or the fulfillment order cannot be put 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.

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.

Behavior

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.

Errors

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

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

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 [Idempotency](/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.
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.

400Order or fulfillment order not found, or the fulfillment 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.

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.

Behavior

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.

Errors

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

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 [Idempotency](/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.

400Cannot allocate fulfillment order.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 →

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.

Errors

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

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.

400Cannot list available locations.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 →

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.

Errors

400 — none of the rule ids resolve.

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.

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>