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.
orders:writeGrant 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 ofsales_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
- 201
- 401
- 403
- 409
- 422
- 429
Created
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Conflict
Response Headers
Unprocessable Content
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.