Skip to main content

Merge Sales Orders Into One Shipment

POST 

/api/sales-orders/merge

Merge two or more open, not-yet-dispatched sales orders for the same ship-to address into one shipment. The warehouse / 3PL receives a single order under the primary order's reference and ships one package; when it ships, each sales order records its own fulfillment with the shared tracking number, and that tracking is posted to each order's own sales channel order. A note naming the other orders is added to each order. If one of the orders is already in a merged shipment, the others are added to it.

Required scope: orders:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

The eligibility check from Preview Sales Order Merge runs again on the server; nothing is written when it fails.

Body fields:

  • sales_order_ids (required, array of 2-50 distinct sales order ids).
  • primary_sales_order_id (optional, integer, nullable): which order's reference the warehouse / 3PL receives the merged shipment under. Must be one of sales_order_ids. Defaults to the oldest order (or the existing primary when extending a merged shipment).

Returns 201 with the merged shipment and its members. 422 with error, every blockers reason and the preview when the orders cannot merge; 409 when an order changed after the preview (for example it was just sent to the 3PL).

Authentication: Requires Bearer token. A token also needs its orders scope.

Required permission: fulfillment_orders.update (Fulfillment Orders → Edit), plus fulfillment_orders.index (Fulfillment Orders → View) and sales_orders.index (Sales Orders → View).

Request​

Responses​

Created

Response Headers
    Content-Type