Skip to main content

Swap Line to Substitute Product

POST 

/api/sales-order-lines/:salesOrderLineId/swap

Non-destructively swap the line to an equivalent product. The line keeps its price, description and channel identity; its product becomes the substitute (so allocation, fulfillment, picking and costing all operate on the SKU that ships) and the ordered product is preserved — the packing slip keeps printing the SKU the customer ordered, while the pick list shows the substitute annotated with the original.

Required scope: orders:write

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

Authentication: Requires Bearer token.

product_substitution_id records which rule drove the swap when the target came from a suggestion; omit it for a one-off substitute.

Blocked with 409 when the line is committed to fulfillment (fulfilled units or an in-flight fulfillment) — void or cancel the fulfillment first. Returns the refreshed sales order.

Set after_fulfillment to true to swap a line that is already submitted or shipped. The sales channel line and tracking are unchanged and the fulfillment provider is not contacted. Units not yet shipped re-allocate to the new product. Units already shipped return to the old product's stock and are deducted from the new product at the original ship date, and cost of goods updates to match. Returns 409 if the new product doesn't have enough stock, or if the line is a bundle or dropship line, has a return or credit, is on an open pick list, has a serial-tracked shipment, or shipped in a locked accounting period.

Request​

Responses​

OK

Response Headers
    Content-Type