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.
orders:writeGrant 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
- 200
- 401
- 403
- 404
- 409
- 422
- 429
OK
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.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
Conflict
Response Headers
Validation failed — the body is a field → messages map (Laravel shape) or the platform envelope with a stable machine-readable code. Fix the payload and resubmit.
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.