Fulfillment API
The Carriyo Fulfillment API covers the work between order allocation and carrier handoff: picking items off shelves, packing them into parcels, and managing customer-collection handovers. Bin-location mappings for the Fulfillment App are also managed here.
Access
Every request needs the matching scope on the API client. Picks, packs and collections sit under /orders and are covered by the orders scope; bin locations need the bin-locations scope. A 403 on a documented endpoint means the client lacks the scope, not that the endpoint is unavailable.
Idempotency
Write endpoints accept an optional Idempotency-Key request header for safe request replay when your integration retries after uncertain network outcomes, except Remove a package and Send pickup OTP to customer. Replayed responses include Idempotent-Replayed: true. See Idempotency for the full contract.
Picks
A pick is a picker's work order: the line items to pull from the shelves at one fulfillment location, for one or more fulfillment orders. It is created open, starts into processing, and ends completed or cancelled, pausing in stopped when cancelled with items already picked. Picks are reached only through the lookup reads by order or fulfillment order, which return summaries.
Picks emit no webhook, and no pick operation fires the order webhook, automatic creation included. Poll the order or the pick for changes.
Related: How picks move line items through the pick lifecycle
11 operations · 0 objects
/orders/picksCreate a pick
Creates a pick for line items of one or more fulfillment orders at a single location, and moves those line items into picking.
Behavior
What to send
partner_location_id, the Carriyo location id, and at least one item, each naming its order_id, fulfillment_order_id, line_item_id and quantity. Every item must belong to a fulfillment order at that location.
- Only an
allocatedline item can be picked, andquantitymay not exceed its quantity. - A line item already in a non-terminal pick is refused.
- A pick is refused while the order or the fulfillment order is on hold.
- With split picking disabled in the location's Fulfillment App settings, every non-terminal line item of each fulfillment order must be included.
With auto_create_picks on in the location's Fulfillment App settings, Carriyo creates one pick per fulfillment order itself, skipping held orders. It does so on order creation, on allocation, and on a location update that gives the fulfillment order its first location. A manual create is then only for line items not already in a pick.
Pick type
- One fulfillment order gives an
ORDER_PICK, even when only some of its items are included. - Several fulfillment orders give a
CLUSTER_PICKwhen every included fulfillment order is fully covered, otherwise aZONE_PICK. - Several fulfillment orders need cluster picking enabled in the location's Fulfillment App settings. Any fulfillment order not fully included needs split picking enabled, an
ORDER_PICKof some items too; so aZONE_PICKneeds both.
Picker
picker must hold the Fulfillment App's pick permission at that location. On create, a picker without it is dropped silently and the pick is created without one; Reassign a pick rejects it instead.
Without a picker, assignment follows the location's picker assignment strategy: manual and round_robin leave the pick unassigned, work_load assigns the least-loaded eligible picker.
What happens
- Each line item moves from
allocatedtopick_in_progress. Aquantitybelow the line item's splits it: the requested quantity moves into picking as a new line item and the remainder staysallocated. - The pick is created in
openwith itspick_typeand a pick list document. - The order status is recalculated. No webhook fires.
Errors
400—partner_location_idis blank.400—itemsis empty.400— an item belongs to a fulfillment order at another location.400— a line item is notallocated.400— a line item is already in a non-terminal pick.400— aquantityexceeds the line item's quantity.400— the order or the fulfillment order is on hold.400— the items span more than one fulfillment order with cluster picking disabled.400— the items leave out line items of a fulfillment order with split picking disabled.
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
application/jsonSchema: pick-requestrequired- The picker's scoped user key as it appears in Fulfillment App access:
global~<email>, orCarriyo-SSO::<provider>~<id>for SSO users; a bare email is not a valid key. The user must holdpickpermission atpartner_location_id; theiron_dutyflag is not checked, since onlywork_loadassignment uses it. When omitted, the location's picker assignment strategy applies.
Responses
pick-response- Set from the items at creation:
ORDER_PICKwhen all items belong to one fulfillment order,CLUSTER_PICKwhen several fulfillment orders are each fully included,ZONE_PICKwhen several are included and any only partly. Several fulfillment orders need cluster picking enabled at the location and any partly included fulfillment order needs split picking enabled, soZONE_PICKneeds both.Values:ORDER_PICKZONE_PICKCLUSTER_PICK
Need the full machine-readable spec? Download the OpenAPI document →
/orders/picks/{pickId}Get a pick
Returns the full pick, including its items, documents and timestamps.
Errors
400—pickIdis unknown.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| pickId | string | Yes | The pick identifier (e.g. `PIK_123`). |
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
pick-response- Set from the items at creation:
ORDER_PICKwhen all items belong to one fulfillment order,CLUSTER_PICKwhen several fulfillment orders are each fully included,ZONE_PICKwhen several are included and any only partly. Several fulfillment orders need cluster picking enabled at the location and any partly included fulfillment order needs split picking enabled, soZONE_PICKneeds both.Values:ORDER_PICKZONE_PICKCLUSTER_PICK
Need the full machine-readable spec? Download the OpenAPI document →
/orders/picks/order/{orderId}List picks for an order
Returns lookup summaries of the picks associated with an order.
Behavior
Each entry carries pick_id, tenant, partner_location_id, status and creation_date, never the items or documents; read the full pick by pick_id. An unknown orderId returns an empty array, not an error.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| orderId | string | Yes | The order identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
An array of pick-response. Each item has the following fields:
- Set from the items at creation:
ORDER_PICKwhen all items belong to one fulfillment order,CLUSTER_PICKwhen several fulfillment orders are each fully included,ZONE_PICKwhen several are included and any only partly. Several fulfillment orders need cluster picking enabled at the location and any partly included fulfillment order needs split picking enabled, soZONE_PICKneeds both.Values:ORDER_PICKZONE_PICKCLUSTER_PICK
Need the full machine-readable spec? Download the OpenAPI document →
/orders/picks/fulfillment-order/{fulfillmentOrderId}List picks for a fulfillment order
Returns lookup summaries of the picks associated with a fulfillment order.
Behavior
Each entry carries pick_id, tenant, partner_location_id, status and creation_date, never the items or documents; read the full pick by pick_id. An unknown fulfillmentOrderId returns an empty array, not an error.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| fulfillmentOrderId | string | Yes | The fulfillment order identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
An array of pick-response. Each item has the following fields:
- Set from the items at creation:
ORDER_PICKwhen all items belong to one fulfillment order,CLUSTER_PICKwhen several fulfillment orders are each fully included,ZONE_PICKwhen several are included and any only partly. Several fulfillment orders need cluster picking enabled at the location and any partly included fulfillment order needs split picking enabled, soZONE_PICKneeds both.Values:ORDER_PICKZONE_PICKCLUSTER_PICK
Need the full machine-readable spec? Download the OpenAPI document →
/orders/picks/{pickId}/startStart a pick
Moves an open pick to processing and sets start_date.
Behavior
The pick must be open and have a picker, set by Create a pick or Reassign a pick. No request body is needed.
Errors
400—pickIdis unknown.400— the pick is notopen.400— the pick has nopicker.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| pickId | string | Yes | The pick identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
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
pick-response- Set from the items at creation:
ORDER_PICKwhen all items belong to one fulfillment order,CLUSTER_PICKwhen several fulfillment orders are each fully included,ZONE_PICKwhen several are included and any only partly. Several fulfillment orders need cluster picking enabled at the location and any partly included fulfillment order needs split picking enabled, soZONE_PICKneeds both.Values:ORDER_PICKZONE_PICKCLUSTER_PICK
Need the full machine-readable spec? Download the OpenAPI document →
/orders/picks/{pickId}/cancelCancel a pick
Cancels a pick and returns its line items to allocated, or stops it when items have already been picked.
Behavior
Outcome.
- An
openorstoppedpick, or aprocessingpick with nothing picked, becomescancelledwithcancel_date; its line items return toallocated. - A
processingpick with any picked quantity becomesstoppedinstead; its line items staypick_in_progressand the order is not touched. Cancel astoppedpick again to cancel it fully; it still accepts Restock items back to shelf first, to record items returned to the shelf.
Reason. reason_code is optional and stored on the pick. The body may be omitted.
Errors
400—pickIdis unknown.400— the pick iscompleted.400— the pick is alreadycancelled.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| pickId | string | Yes | The pick identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
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
application/jsonSchema: cancel-pick-requestResponses
pick-response- Set from the items at creation:
ORDER_PICKwhen all items belong to one fulfillment order,CLUSTER_PICKwhen several fulfillment orders are each fully included,ZONE_PICKwhen several are included and any only partly. Several fulfillment orders need cluster picking enabled at the location and any partly included fulfillment order needs split picking enabled, soZONE_PICKneeds both.Values:ORDER_PICKZONE_PICKCLUSTER_PICK
Need the full machine-readable spec? Download the OpenAPI document →
/orders/picks/{pickId}/reassignReassign a pick
Assigns or replaces the picker on an open pick.
Behavior
picker is required, and the user must hold the Fulfillment App's pick permission at the pick's location. Unlike Create a pick, which drops such a picker silently, an invalid picker is rejected here.
Errors
400—pickIdis unknown.400— the pick is notopen.400—pickeris missing.400—pickerhas no pick permission at the pick's location.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| pickId | string | Yes | The pick identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
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
application/jsonSchema: reassign-pick-requestrequiredResponses
pick-response- Set from the items at creation:
ORDER_PICKwhen all items belong to one fulfillment order,CLUSTER_PICKwhen several fulfillment orders are each fully included,ZONE_PICKwhen several are included and any only partly. Several fulfillment orders need cluster picking enabled at the location and any partly included fulfillment order needs split picking enabled, soZONE_PICKneeds both.Values:ORDER_PICKZONE_PICKCLUSTER_PICK
Need the full machine-readable spec? Download the OpenAPI document →
/orders/picks/{pickId}/completeComplete a pick
Completes a processing pick, moving its line items to picked and handing them over for packing.
Behavior
Preconditions. The pick must be processing and every item fully resolved: quantity_picked plus its mispicked quantities equals quantity. No request body is needed.
What happens. The pick becomes completed and each line item is settled by what was picked:
- fully picked, it moves from
pick_in_progresstopicked; - partly picked with mispicks, it moves to
pickedwith its quantity reduced to the picked amount; - with nothing picked, it is
cancelled.
Mispicked remainder. The mispicked units of a partly picked line item are dropped. No cancelled line item is created for them, nothing returns to allocated, and the order's own line item is unchanged.
Nothing picked. When nothing at all was picked across the pick, the pick becomes cancelled instead of completed and every line item returns to allocated.
Errors
400—pickIdis unknown.400— the pick is notprocessing.400— an item is not fully picked or mispicked.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| pickId | string | Yes | The pick identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
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
pick-response- Set from the items at creation:
ORDER_PICKwhen all items belong to one fulfillment order,CLUSTER_PICKwhen several fulfillment orders are each fully included,ZONE_PICKwhen several are included and any only partly. Several fulfillment orders need cluster picking enabled at the location and any partly included fulfillment order needs split picking enabled, soZONE_PICKneeds both.Values:ORDER_PICKZONE_PICKCLUSTER_PICK
Need the full machine-readable spec? Download the OpenAPI document →
/orders/picks/{pickId}/items/pickRecord items picked off shelf
Records quantities the picker has taken from the shelf, adding to each item's quantity_picked.
Behavior
What to send. A JSON array of {fulfillment_order_id, line_item_id, quantity}, each entry naming an item of the pick. The pick must be processing.
What happens. Each quantity is added to the item's quantity_picked. It must not exceed what remains: quantity less quantity_picked less its mispicked quantities. Calls accumulate, and line items stay pick_in_progress until the pick completes.
Validation. One invalid entry rejects the whole call, and nothing is saved.
Errors
400—pickIdis unknown.400— the pick is notprocessing.400— an entry names a line item that is not in the pick.400— aquantityexceeds what remains to pick; the message gives the available quantity.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| pickId | string | Yes | The pick identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
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
application/jsonrequiredAn array of pick-item-action-request. Each item has the following fields:
Responses
pick-response- Set from the items at creation:
ORDER_PICKwhen all items belong to one fulfillment order,CLUSTER_PICKwhen several fulfillment orders are each fully included,ZONE_PICKwhen several are included and any only partly. Several fulfillment orders need cluster picking enabled at the location and any partly included fulfillment order needs split picking enabled, soZONE_PICKneeds both.Values:ORDER_PICKZONE_PICKCLUSTER_PICK
Need the full machine-readable spec? Download the OpenAPI document →
/orders/picks/{pickId}/items/restockRestock items back to shelf
Records quantities put back on the shelf, reducing each item's quantity_picked.
Behavior
What to send. A JSON array of {fulfillment_order_id, line_item_id, quantity}, each entry naming an item of the pick. The pick must be processing or stopped.
What happens. Each quantity is taken off the item's quantity_picked and must not exceed it. Line item statuses do not change.
Validation. One invalid entry rejects the whole call, and nothing is saved.
Errors
400—pickIdis unknown.400— the pick is notprocessingorstopped.400— an entry names a line item that is not in the pick.400— aquantityexceeds the item'squantity_picked; the message gives the picked quantity.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| pickId | string | Yes | The pick identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
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
application/jsonrequiredAn array of pick-item-action-request. Each item has the following fields:
Responses
pick-response- Set from the items at creation:
ORDER_PICKwhen all items belong to one fulfillment order,CLUSTER_PICKwhen several fulfillment orders are each fully included,ZONE_PICKwhen several are included and any only partly. Several fulfillment orders need cluster picking enabled at the location and any partly included fulfillment order needs split picking enabled, soZONE_PICKneeds both.Values:ORDER_PICKZONE_PICKCLUSTER_PICK
Need the full machine-readable spec? Download the OpenAPI document →
/orders/picks/{pickId}/items/mispickRecord mispicked items
Records quantities that could not be picked, with a reason, on each item's mispicks.
Behavior
What to send. A JSON array of {fulfillment_order_id, line_item_id, quantity, reason}, each entry naming an item of the pick. The pick must be processing.
What happens. Each entry is appended to the item's mispicks as a record of quantity and reason. The quantity must not exceed what remains: quantity less quantity_picked less mispicks already recorded. Nothing is decremented, and line items keep their status until Complete a pick settles them.
Validation. One invalid entry rejects the whole call, and nothing is saved.
Errors
400—pickIdis unknown.400— the pick is notprocessing.400— an entry names a line item that is not in the pick.400— aquantityexceeds what remains; the message gives the available quantity.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| pickId | string | Yes | The pick identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
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
application/jsonrequiredAn array of mispick-item-request. Each item has the following fields:
Responses
pick-response- Set from the items at creation:
ORDER_PICKwhen all items belong to one fulfillment order,CLUSTER_PICKwhen several fulfillment orders are each fully included,ZONE_PICKwhen several are included and any only partly. Several fulfillment orders need cluster picking enabled at the location and any partly included fulfillment order needs split picking enabled, soZONE_PICKneeds both.Values:ORDER_PICKZONE_PICKCLUSTER_PICK
Need the full machine-readable spec? Download the OpenAPI document →
Packs
A pack is a packer's work order: the line items to consolidate into packages at a packing station at one fulfillment location, for one or more fulfillment orders. It is created open, starts into processing once a packer and packing station are set, and ends completed or cancelled; completing it is the handover to shipping, or to collection for click-and-collect fulfillment orders. A pack does not need a prior pick, and packs are reached only through the lookup reads by order, fulfillment order or pick.
Packs have no webhook of their own. Only Complete a pack and Create a shipment from the pack fire the order webhook; after any other pack operation, poll the order or the pack. Complete a pack and Cancel a pack also trigger shipment webhooks through the shipment changes they make.
A local collection is a fulfillment order with delivery_method COLLECTION whose customer_collection_address is absent, names no location, or names the fulfilling location; it needs no shipment. A remote collection is one whose customer_collection_address names another location, and it needs a shipment to get there.
A live shipment is a shipment on a package that is not cancelled. A package with a live shipment cannot be changed, packed, emptied or shipped again; a cancelled shipment does not block.
Related: How packs, packages and shipments fit together
16 operations · 0 objects
/orders/packsCreate a pack
Creates a pack for line items of one or more fulfillment orders at a single location, and moves those line items into packing.
Behavior
What to send
partner_location_id, the Carriyo location id, and at least one item, each naming its order_id, fulfillment_order_id, line_item_id and quantity, and optionally the pick_id it came from. Every item must belong to a fulfillment order at that location.
- A line item is packable when it is
allocatedorpicked; a prior pick is not required.quantitymay not exceed the line item's quantity. - A line item already in a non-terminal pack is refused.
pick_idon an item is optional; when given, that pick must exist and becompleted.- Unlike Create a pick, an order or fulfillment order on hold is not refused.
pick_id and cancel. Cancel a pack returns a line item to picked only when its pack item has a pick_id. Leave pick_id out on a picked line item and a cancel returns it to allocated.
Packer and packing station
packer and packing_station are optional, and neither is validated on create: both are stored as sent. Both must be set before Start a pack, which accepts whatever is stored. Only Reassign a pack checks them: packer for the Fulfillment App's pack permission at the location, and packing_station for existence at the location.
What happens
- Each line item moves from
allocatedorpickedtopack_in_progress. Aquantitybelow the line item's splits it, the remainder keeping its status. - The pack is created in
openwith a packing list document and no packages.packagesis absent until you call Add a package to the pack, or Reset packages on the pack, which creates one default package per fulfillment order.
Errors
400—partner_location_idis blank.400—itemsis empty.400— an item belongs to a fulfillment order at another location.400— a line item is neitherallocatednorpicked.400— a line item is already in a non-terminal pack.400— aquantityexceeds the line item's quantity.400—pick_idnames a pick that does not exist.400—pick_idnames a pick that is notcompleted.
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
application/jsonSchema: pack-requestrequired- The packer's scoped user key as it appears in Fulfillment App access:
global~<email>, orCarriyo-SSO::<provider>~<id>for SSO users; a bare email is not a valid key. Optional at creation but required before Start a pack, and stored as sent without checks. Reassign a pack checks that the user haspackpermission atpartner_location_id, ignoring theiron_dutyflag.
Responses
pack-responseNeed the full machine-readable spec? Download the OpenAPI document →
/orders/packs/{packId}Get a pack
Returns the full pack, including its items, packages, documents and timestamps.
Errors
400—packIdis unknown.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| packId | string | Yes | The pack identifier (e.g. `PAK_123`). |
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
pack-responseNeed the full machine-readable spec? Download the OpenAPI document →
/orders/packs/order/{orderId}List packs for an order
Returns lookup summaries of the packs associated with an order.
Behavior
Each entry carries pack_id, tenant, partner_location_id, status and creation_date, never the items or packages; read the full pack by pack_id. An unknown orderId returns an empty array, not an error.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| orderId | string | Yes | The order identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
An array of pack-response. Each item has the following fields:
Need the full machine-readable spec? Download the OpenAPI document →
/orders/packs/fulfillment-order/{fulfillmentOrderId}List packs for a fulfillment order
Returns lookup summaries of the packs associated with a fulfillment order.
Behavior
Each entry carries pack_id, tenant, partner_location_id, status and creation_date, never the items or packages; read the full pack by pack_id. An unknown fulfillmentOrderId returns an empty array, not an error.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| fulfillmentOrderId | string | Yes | The fulfillment order identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
An array of pack-response. Each item has the following fields:
Need the full machine-readable spec? Download the OpenAPI document →
/orders/packs/pick/{pickId}List packs for a pick
Returns lookup summaries of the packs whose items reference a pick.
Behavior
Each entry carries pack_id, tenant, partner_location_id, status and creation_date, never the items or packages; read the full pack by pack_id. An unknown pickId returns an empty array, not an error.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| pickId | string | Yes | The pick identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
An array of pack-response. Each item has the following fields:
Need the full machine-readable spec? Download the OpenAPI document →
/orders/packs/{packId}/startStart a pack
Moves an open pack to processing and sets start_date.
Behavior
The pack must be open and have both a packer and a packing_station, set by Create a pack or Reassign a pack. Neither is validated here. No request body is needed.
Errors
400—packIdis unknown.400— the pack is notopen.400— the pack has nopacker.400— the pack has nopacking_station.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| packId | string | Yes | The pack identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
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
pack-responseNeed the full machine-readable spec? Download the OpenAPI document →
/orders/packs/{packId}/reassignReassign a pack
Assigns or replaces the packer, the packing station, or both on an open pack.
Behavior
Send packer, packing_station or both; whichever is sent is set and the other is left as it is. packer must hold the Fulfillment App's pack permission at the pack's location, and packing_station must exist at that location. Unlike Create a pack, which stores both as sent, an invalid value is rejected here.
Errors
400—packIdis unknown.400— the pack is notopen.400— neitherpackernorpacking_stationis sent.400—packerhas no pack permission at the pack's location.400—packing_stationdoes not exist at the pack's location.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| packId | string | Yes | The pack identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
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
application/jsonSchema: reassign-pack-requestrequiredResponses
pack-responseNeed the full machine-readable spec? Download the OpenAPI document →
/orders/packs/{packId}/packagesAdd a package to the pack
Adds an empty package to a pack and returns its generated package_id.
Behavior
The pack must be open or processing. The package's order_id and fulfillment_order_id must be those of items in the pack; a package belongs to that one fulfillment order, and only its items can be packed into it. Put items into it with Place items into packages.
Errors
400—packIdis unknown.400— the pack is notopenorprocessing.400—order_idis not in the pack.400—fulfillment_order_idis not in the pack.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| packId | string | Yes | The pack identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
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
application/jsonSchema: add-package-requestrequiredResponses
pack-responseNeed the full machine-readable spec? Download the OpenAPI document →
/orders/packs/{packId}/packages/{packageId}Update a package
Updates a package's physical properties; only the fields sent are changed.
Behavior
The pack must be open or processing, and the package must have no live shipment; once a shipment exists for the package, update the shipment itself. Only package_type, dimension, empty_weight and max_weight are changed, each when present.
weight cannot be set here or by any other pack operation, so Create a shipment from the pack uses empty_weight as the parcel weight.
Errors
400—packIdis unknown.400—packageIdis not in the pack.400— the pack is notopenorprocessing.400— the package has a live shipment.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| packId | string | Yes | The pack identifier. |
| packageId | string | Yes | The package identifier (e.g. `PKG_456`). |
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
application/jsonSchema: update-package-requestrequiredResponses
pack-responseNeed the full machine-readable spec? Download the OpenAPI document →
/orders/packs/{packId}/packages/{packageId}Remove a package
Removes a package from a pack, unpacking its items first.
Behavior
The pack must be open or processing, and the package must have no live shipment. Its items are unpacked first, reducing quantity_packed on their pack items, then the package is removed. This is the one write on a pack that does not accept Idempotency-Key.
Errors
400—packIdis unknown.400—packageIdis not in the pack.400— the pack is notopenorprocessing.400— the package has a live shipment.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| packId | string | Yes | The pack identifier. |
| packageId | string | Yes | The package identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
pack-responseNeed the full machine-readable spec? Download the OpenAPI document →
/orders/packs/{packId}/reset-packagesReset packages on the pack
Discards all packing progress on a pack, leaving one empty default package per fulfillment order.
Behavior
The pack must be open or processing, and no package may have a live shipment. Every item's quantity_packed returns to 0 and the packages are replaced. No request body is needed.
Errors
400—packIdis unknown.400— the pack is notopenorprocessing.400— a package has a live shipment.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| packId | string | Yes | The pack identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
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
pack-responseNeed the full machine-readable spec? Download the OpenAPI document →
/orders/packs/{packId}/items/packPlace items into packages
Places quantities of line items into a package, adding to each item's quantity_packed.
Behavior
What to send. A JSON array, each entry naming an item of the pack by fulfillment_order_id and line_item_id, the target package_id and a quantity. The pack must be processing. The package must exist in the pack, belong to the item's fulfillment order and have no live shipment.
Selection method. selection_method (SCANNER, CAMERA or MANUAL) is optional and records how the item was identified. It is stored on the pack item, and omitting it clears a value an earlier call recorded.
What happens. Each quantity is added to the item's quantity_packed and must not exceed what remains: quantity less quantity_packed. The package's items entry carries line_item_id and quantity. Calls accumulate, and one invalid entry rejects the whole call with nothing saved.
Errors
400—packIdis unknown.400— the pack is notprocessing.400— an entry names a line item that is not in the pack.400— aquantityexceeds what remains to pack; the message gives the available quantity.400—package_idis not in the pack.400—package_idbelongs to another fulfillment order.400—package_idhas a live shipment.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| packId | string | Yes | The pack identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
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
application/jsonrequiredAn array of pack-item-action-request. Each item has the following fields:
Responses
pack-responseNeed the full machine-readable spec? Download the OpenAPI document →
/orders/packs/{packId}/items/unpackRemove items from packages
Removes quantities of line items from a package, reducing each item's quantity_packed.
Behavior
What to send. A JSON array, each entry naming the package_id, the line_item_id packed in it, and a quantity no greater than what is packed there. The fulfillment order is taken from the package. The pack must be processing, and the package must have no live shipment.
What happens. Each quantity is taken off the item's quantity_packed and off the package's entry for it, which is removed at zero. One invalid entry rejects the whole call, and nothing is saved.
Errors
400—packIdis unknown.400— the pack is notprocessing.400—package_idis not in the pack.400— the package has a live shipment.400— the line item is not packed in that package.400— aquantityexceeds what is packed in that package; the message gives the packed quantity.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| packId | string | Yes | The pack identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
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
application/jsonrequiredAn array of unpack-item-action-request. Each item has the following fields:
Responses
pack-responseNeed the full machine-readable spec? Download the OpenAPI document →
/orders/packs/{packId}/completeComplete a pack
Completes a processing pack: fulfills the packed items, asks their shipments to become ready to ship, and creates collections for collection fulfillment orders.
Behavior
Preconditions
- The pack must be
processing, have items, and every item must be fully packed. - Every package holding non-digital items must already have a shipment, created with Create a shipment from the pack, unless its fulfillment order is a local collection. An item is digital when its order line item has
digitalset. ship_zoneis required when any package has a shipment. It is the id of a ship zone configured at the location the shipments pick up from.
No other shipment state is checked, so the pack completes while a shipment is still pending booking.
Fulfillment
The pack becomes completed. For each fulfillment order, the packed quantities are fulfilled under a new fulfillment_id, moving the line items to fulfilled. No partner_fulfillment_reference is set, because the body accepts only ship_zone, and no new shipment is created. A fully fulfilled line item keeps the shipment_ids that Create a shipment from the pack added.
Webhooks
One FULFILLMENT_ORDER_FULFILL order webhook fires per fulfillment order. Its payload does not carry the new collection_ids, which are saved afterwards without a webhook; read the order to get them.
Shipments
Asynchronously, ship_zone is applied to each shipment and each shipment is asked to become ready to ship; the outcomes arrive through the shipment webhooks. An unknown ship_zone is dropped silently. A shipment with no carrier cannot become ready to ship until one is assigned.
Collections
A collection is created for each fulfillment order with delivery_method COLLECTION that carries a customer_collection_address. It starts open with that fulfillment order's packages that hold items and the order's customer, and its id is added to the line items' collection_ids.
- A local collection with a
customer_collection_addressneeds no shipment and gets a collection. - A remote collection needs a shipment and also gets a collection.
- A local collection without a
customer_collection_addressneeds no shipment and never gets a collection.
Errors
400—packIdis unknown.400— the pack is notprocessing.400— the pack has no items.400— an item is not fully packed.400— a package requires shipping but has no shipment.400—ship_zoneis missing while a package has a shipment.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| packId | string | Yes | The pack identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
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
application/jsonSchema: complete-pack-requestResponses
pack-responseNeed the full machine-readable spec? Download the OpenAPI document →
/orders/packs/{packId}/cancelCancel a pack
Cancels a pack, cancels the live shipments on its packages, and returns its line items to picked or allocated.
Behavior
Outcome. The pack becomes cancelled whatever has been packed; unlike a pick, a pack has no stopped state.
- Each line item returns to
pickedwhen its pack item has apick_id, otherwise toallocated. - Every live shipment on the pack's packages is cancelled, and shipment webhooks fire for them.
Reason. reason_code is optional and stored on the pack. The body may be omitted.
Errors
400—packIdis unknown.400— the pack iscompleted.400— the pack is alreadycancelled.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| packId | string | Yes | The pack identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
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
application/jsonSchema: cancel-pack-requestResponses
pack-responseNeed the full machine-readable spec? Download the OpenAPI document →
/orders/packs/{packId}/create-shipmentCreate a shipment from the pack
Creates a confirmed shipment for selected packages of a pack, one parcel per package.
Behavior
What to send
package_ids, at least one. Every package must exist in the pack, hold packed items and have no live shipment; all of them must belong to one order and one fulfillment order.
The pack must be processing, and the fulfillment order must not be a local collection. A local collection gets its collection when the pack completes, provided it carries a customer_collection_address.
Carrier
carrier_account.carrier_id, the carrier account id, is optional and must resolve to a carrier account when sent; carrier_account_name is ignored. Without it, the tenant's shipping rules choose the carrier when the shipment is booked.
What happens
The shipment is created confirmed, not as a draft, with one parcel per selected package, in order. The shipment assigns each parcel_id (for example <shipment_id>-1), the parcel description carries the package type, the dimension is copied, and parcel_items carries the SKUs and quantities.
The parcel weight is the package's empty_weight, because no pack operation sets the package weight.
shipment_id is stamped on each package, and an earlier id moves to previous_shipment_ids. The response is the full pack; the shipment id appears as packages[].shipment_id.
Webhook. The order webhook fires with FULFILLMENT_ORDER_SHIP_LINE_ITEMS.
Errors
400—packIdis unknown.400— the pack is notprocessing.400—package_idsis empty.400— a package is not in the pack.400— a package has no packed items.400— a package has a live shipment.400— the packages span more than one order or fulfillment order.400— the fulfillment order is a local collection.400—carrier_account.carrier_iddoes not resolve to a carrier account.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| packId | string | Yes | The pack identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
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
application/jsonSchema: create-pack-shipment-requestrequiredResponses
pack-responseNeed the full machine-readable spec? Download the OpenAPI document →
Collections
A collection is the customer-pickup record for a click-and-collect fulfillment order: the packages waiting at the collection point and the customer who will collect them, verified by a one-time code at handover. It is created open, is marked ready_to_collect when the packages are at the collection point, and ends collected or cancelled, passing through expired when the customer does not come within the expiry window. Collections are never created directly: when a pack completes, one is created for each fulfillment order with delivery_method COLLECTION that carries a customer_collection_address. A collection is reached through the lookup reads by order, fulfillment order or pack.
Collections emit no webhook, and no collection operation fires the order webhook, collect included; the only message sent is the one-time code email. Poll the collection or the order for changes.
Related: How customer collections are created, verified and expire
11 operations · 0 objects
/orders/collections/{collectionId}Get a collection
Returns the full collection, including its packages, customer, verification state and timestamps.
Errors
400—collectionIdis unknown.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| collectionId | string | Yes | The collection identifier (e.g. `COL_123`). |
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
collection-response- Lifecycle state:
open(not yet at the collection point),ready_to_collect(customer can be notified and verified),expired(collection window passed; Reverse auto-expiry returns it toready_to_collect).collectedandcancelledare terminal.Values:openready_to_collectcollectedexpiredcancelled
Need the full machine-readable spec? Download the OpenAPI document →
/orders/collections/order/{orderId}List collections for an order
Returns lookup summaries of the collections associated with an order.
Behavior
Each entry carries collection_id, tenant, partner_location_id, status and creation_date, never the packages or customer; read the full collection by collection_id. An unknown orderId returns an empty array, not an error.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| orderId | string | Yes | The order identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
An array of collection-response. Each item has the following fields:
- Lifecycle state:
open(not yet at the collection point),ready_to_collect(customer can be notified and verified),expired(collection window passed; Reverse auto-expiry returns it toready_to_collect).collectedandcancelledare terminal.Values:openready_to_collectcollectedexpiredcancelled
Need the full machine-readable spec? Download the OpenAPI document →
/orders/collections/fulfillment-order/{fulfillmentOrderId}List collections for a fulfillment order
Returns lookup summaries of the collections associated with a fulfillment order.
Behavior
Each entry carries collection_id, tenant, partner_location_id, status and creation_date, never the packages or customer; read the full collection by collection_id. An unknown fulfillmentOrderId returns an empty array, not an error.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| fulfillmentOrderId | string | Yes | The fulfillment order identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
An array of collection-response. Each item has the following fields:
- Lifecycle state:
open(not yet at the collection point),ready_to_collect(customer can be notified and verified),expired(collection window passed; Reverse auto-expiry returns it toready_to_collect).collectedandcancelledare terminal.Values:openready_to_collectcollectedexpiredcancelled
Need the full machine-readable spec? Download the OpenAPI document →
/orders/collections/pack/{packId}List collections for a pack
Returns lookup summaries of the collections created when a pack completed.
Behavior
Each entry carries collection_id, tenant, partner_location_id, status and creation_date, never the packages or customer; read the full collection by collection_id. An unknown packId returns an empty array, not an error.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| packId | string | Yes | The pack identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
An array of collection-response. Each item has the following fields:
- Lifecycle state:
open(not yet at the collection point),ready_to_collect(customer can be notified and verified),expired(collection window passed; Reverse auto-expiry returns it toready_to_collect).collectedandcancelledare terminal.Values:openready_to_collectcollectedexpiredcancelled
Need the full machine-readable spec? Download the OpenAPI document →
/orders/collections/shipment/{shipmentId}List collections for a shipment
Returns lookup summaries of the collections linked to a shipment.
Behavior
This read answers an empty array for every shipmentId: a collection is not linked to a shipment when it is created, so none is ever found here. Find a collection through its order, fulfillment order or pack instead.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| shipmentId | string | Yes | The shipment identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
An array of collection-response. Each item has the following fields:
- Lifecycle state:
open(not yet at the collection point),ready_to_collect(customer can be notified and verified),expired(collection window passed; Reverse auto-expiry returns it toready_to_collect).collectedandcancelledare terminal.Values:openready_to_collectcollectedexpiredcancelled
Need the full machine-readable spec? Download the OpenAPI document →
/orders/collections/{collectionId}/readyMark collection ready for pickup
Moves an open collection to ready_to_collect and sets ready_date.
Behavior
The collection must be open. No request body is needed.
Expiry. With customer_collection_auto_expire_enabled on in the order management settings, the collection becomes expired on its own customer_collection_auto_expire_days after ready_date, 7 when unset. With customer_collection_auto_cancel_enabled also on and customer_collection_auto_cancel_days set above 0, an expired collection is then cancelled on its own after that many days, with reason auto_cancelled. Both settings are checked again at the moment of expiry or cancellation, so turning one off in the meantime stops it.
Errors
400—collectionIdis unknown.400— the collection is notopen.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| collectionId | string | Yes | The collection identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
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
collection-response- Lifecycle state:
open(not yet at the collection point),ready_to_collect(customer can be notified and verified),expired(collection window passed; Reverse auto-expiry returns it toready_to_collect).collectedandcancelledare terminal.Values:openready_to_collectcollectedexpiredcancelled
Need the full machine-readable spec? Download the OpenAPI document →
/orders/collections/{collectionId}/reopenReopen a collection
Returns a ready_to_collect collection to open.
Behavior
The collection must be ready_to_collect. ready_date and the expiry date are cleared, and the verification is reset to pending, discarding any one-time code and its attempt count. No request body is needed.
Errors
400—collectionIdis unknown.400— the collection is notready_to_collect.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| collectionId | string | Yes | The collection identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
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
collection-response- Lifecycle state:
open(not yet at the collection point),ready_to_collect(customer can be notified and verified),expired(collection window passed; Reverse auto-expiry returns it toready_to_collect).collectedandcancelledare terminal.Values:openready_to_collectcollectedexpiredcancelled
Need the full machine-readable spec? Download the OpenAPI document →
/orders/collections/{collectionId}/cancelCancel a collection
Cancels a collection, clearing its verification state and any pending expiry or auto-cancel schedule.
Behavior
Outcome. The collection becomes cancelled from open, ready_to_collect or expired. Only the collection changes: its packages and the fulfillment order's line items are untouched, so the line items stay fulfilled.
No replacement. There is no way to create another collection for those line items. Line items close only through Verify OTP and complete handover, once every collection they belong to is collected or cancelled.
Reason. cancellation_reason is optional and stored on the collection. The body may be omitted.
Errors
400—collectionIdis unknown.400— the collection is alreadycollected.400— the collection is alreadycancelled.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| collectionId | string | Yes | The collection identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
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
application/jsonSchema: cancel-collection-requestResponses
collection-response- Lifecycle state:
open(not yet at the collection point),ready_to_collect(customer can be notified and verified),expired(collection window passed; Reverse auto-expiry returns it toready_to_collect).collectedandcancelledare terminal.Values:openready_to_collectcollectedexpiredcancelled
Need the full machine-readable spec? Download the OpenAPI document →
/orders/collections/{collectionId}/unexpireReverse auto-expiry
Returns an expired collection to ready_to_collect and starts a fresh expiry window.
Behavior
The collection must be expired. Auto-expiry is scheduled again under the same settings as Mark collection ready for pickup. No request body is needed.
Errors
400—collectionIdis unknown.400— the collection is notexpired.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| collectionId | string | Yes | The collection identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
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
collection-response- Lifecycle state:
open(not yet at the collection point),ready_to_collect(customer can be notified and verified),expired(collection window passed; Reverse auto-expiry returns it toready_to_collect).collectedandcancelledare terminal.Values:openready_to_collectcollectedexpiredcancelled
Need the full machine-readable spec? Download the OpenAPI document →
/orders/collections/{collectionId}/verification/send-otpSend pickup OTP to customer
Generates a 6-digit one-time code and emails it to the customer.
Behavior
The collection must be ready_to_collect and have a customer.email. The code is valid for 5 minutes, and sending one resets the failed-attempt count to 0; a new code can be sent at most once every 60 seconds. No request body is needed.
Customer without an email. This call is refused, and Verify OTP and complete handover needs the verification that only this call creates, override included. Such a collection can never be collected; there is no other path.
The response carries message, otp_sent_at, otp_expires_at and masked_email, the address with only the first and last characters of its local part shown, so staff can tell the customer where to look and how long they have. Each call sends a new email; Idempotency-Key is not supported here.
Errors
400—collectionIdis unknown.400— the collection is notready_to_collect.400— the customer has no email address.400— fewer than 60 seconds have passed since the last send; the message says how long to wait.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| collectionId | string | Yes | The collection identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
Responses
send-otp-responseNeed the full machine-readable spec? Download the OpenAPI document →
/orders/collections/{collectionId}/verification/verify-and-collectVerify OTP and complete handover
Verifies the customer's one-time code, or overrides it, and marks the collection collected.
Behavior
Preconditions
The collection must be ready_to_collect with a one-time code verification in progress, so Send pickup OTP to customer must have been called first, even for an override.
Customer without an email. Such a collection can never be collected. Send pickup OTP to customer needs customer.email, and this call, override included, needs the verification that only Send pickup OTP to customer creates.
Two modes
- Code. Send
otp. It must match the code sent, within its 5 minutes, and before 5 failed attempts. A wrong code is refused with the remaining attempts, and failed attempts are persisted; after the fifth every verify is refused until a new code is sent, which resets the count. On successverification.statusisverified. - Override. Send
override: true; the code is not checked, even whenotpis also sent, andverification.statusisoverridden.overridedefaults tofalse.
What happens
The collection becomes collected with collected_date. The fulfillment order's line items close once every collection they belong to is collected or cancelled; this is evaluated only here, never on cancel.
Errors
400—collectionIdis unknown.400— the collection is notready_to_collect.400— no OTP verification is in progress.400—otpis missing, expired or wrong, or the 5 attempts are used up.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| collectionId | string | Yes | The collection identifier. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
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
application/jsonSchema: verify-and-collect-requestrequiredResponses
collection-response- Lifecycle state:
open(not yet at the collection point),ready_to_collect(customer can be notified and verified),expired(collection window passed; Reverse auto-expiry returns it toready_to_collect).collectedandcancelledare terminal.Values:openready_to_collectcollectedexpiredcancelled
Need the full machine-readable spec? Download the OpenAPI document →
Bin Locations
A bin location is the list of bins that hold one SKU at one fulfillment location; there is one record per location and SKU, and picks read it to stamp bin_locations on their items. Records have no lifecycle: they are created, updated, renamed to a new SKU and deleted directly, or upserted in bulk. Unlike picks, packs and collections, an unknown record here answers 404.
Related: How picks use bin locations
6 operations · 0 objects
/bin-locations/{partnerLocationId}Create bin location
Creates the bin location for a SKU at a fulfillment location: the list of bins that hold it.
Behavior
What to send. sku and bins, the list of bin identifiers that hold it; partner_location_id comes from the path.
Rules. There is one bin location per SKU and location, so a SKU that already has one is refused; call Update bin location or Rename the SKU on a bin-location mapping instead. The location must exist and not be deleted. Returns 201 with the record.
Errors
400— a bin location forskualready exists atpartnerLocationId.400—partnerLocationIdis unknown or deleted.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| partnerLocationId | string | Yes | The Carriyo location id of the fulfillment location. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
Request body
application/jsonSchema: bin-location-requestrequiredResponses
bin-location-responseNeed the full machine-readable spec? Download the OpenAPI document →
/bin-locations/{partnerLocationId}/{sku}Get bin location by SKU
Returns the bin location for a SKU at a fulfillment location.
Errors
404— no bin location exists forskuatpartnerLocationId.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| partnerLocationId | string | Yes | The Carriyo location id of the fulfillment location. |
| sku | string | Yes | SKU. |
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
bin-location-responseNeed the full machine-readable spec? Download the OpenAPI document →
/bin-locations/{partnerLocationId}/{sku}Update bin location
Replaces the bins of a bin location; any other field sent is ignored.
Behavior
Send bins, the full list of bin identifiers. The SKU and the location come from the path.
Errors
404— no bin location exists forskuatpartnerLocationId.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| partnerLocationId | string | Yes | The Carriyo location id of the fulfillment location. |
| sku | string | Yes | SKU. |
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
application/jsonSchema: bin-location-requestrequiredResponses
bin-location-responseNeed the full machine-readable spec? Download the OpenAPI document →
/bin-locations/{partnerLocationId}/{sku}Delete bin location
Deletes the bin location for a SKU at a fulfillment location and returns the deleted record.
Errors
404— no bin location exists forskuatpartnerLocationId.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| partnerLocationId | string | Yes | The Carriyo location id of the fulfillment location. |
| sku | string | Yes | SKU. |
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
bin-location-responseNeed the full machine-readable spec? Download the OpenAPI document →
/bin-locations/{partnerLocationId}/{sku}/update-skuRename the SKU on a bin-location mapping
Renames the SKU of a bin location to new_sku, keeping its bins.
Errors
404— no bin location exists forskuatpartnerLocationId.400— a bin location fornew_skualready exists atpartnerLocationId.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| partnerLocationId | string | Yes | The Carriyo location id of the fulfillment location. |
| sku | string | Yes | Current SKU on the mapping. |
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
application/jsonSchema: update-sku-requestrequiredResponses
bin-location-responseNeed the full machine-readable spec? Download the OpenAPI document →
/bin-locations/{partnerLocationId}/bulk/importBulk import bin locations
Creates or updates up to 200 bin locations at a fulfillment location in one call, reporting the outcome of each row.
Behavior
What happens. Each row is matched by sku: an existing bin location at the location is updated, otherwise one is created. Rows are processed independently, and a row's failure is reported in its result rather than failing the call, so the call succeeds even when every row is rejected. A sku repeated within the request is rejected per row.
Reading the response. One entry per row, with partner_location_id, sku, result (created, updated or rejected), message and, unless rejected, the saved bin_location.
Errors
400— more than 200 items.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| partnerLocationId | string | Yes | The Carriyo location id of the fulfillment location. |
Headers
| Name | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer YOUR-ACCESS-TOKEN | Yes | OAuth 2.0 bearer token obtained from `POST /oauth/token`. |
| x-api-key | YOUR-API-KEY | Yes | Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| tenant-id | YOUR-TENANT-ID | Yes | Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`. |
| Content-Type | application/json | Yes | Media type of the request body. |
Request body
application/jsonrequiredAn array of bin-location-request. Each item has the following fields:
Responses
An array of bin-location-bulk-response. Each item has the following fields:
Need the full machine-readable spec? Download the OpenAPI document →