Skip to main content

Replace Line Product(s)

POST 
/api/sales-order-lines/:salesOrderLine/replace

Replace a single sales order line with one or more SKUs, preserving the line's total amount and the order ↔ sales-channel tie.

Required scope: orders:write

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

Authentication: Requires Bearer token.

Path params:

  • salesOrderLine (required): id of the sales order line to replace.

Body:

  • replacements (required, array, min 1): the target SKUs. Each item:
    • product_id (required, int, must exist in products)
    • quantity (required, number > 0)
    • amount (optional, number >= 0): per-unit price. When omitted on ALL items, the original line total is prorated across the replacements by catalog price; when provided, the explicit amounts must reconcile to the original total (else 422).
  • mapping_mode (optional, one_time | permanent, default one_time): only meaningful for a SINGLE-SKU replacement at the original quantity that resolves to a channel listing. permanent remaps the channel listing so every FUTURE order maps to the new SKU (sets product_mapping_overridden so the line survives a channel resync); one_time changes only this order. Multi-SKU replacements are always one-time.

Returns the refreshed sales order.

Errors:

  • 409: the line is committed to fulfillment (has a fulfillment line or an in-flight/submitted fulfillment order) — void/cancel the fulfillment first.
  • 422: explicit replacement amounts don't reconcile to the line total, or validation failed (unknown product, quantity < 0, missing replacements).

Request​

Responses​

OK

Response Headers
    Content-Type