Skip to main content

Move Fulfillment Order to Different Warehouse

PATCH 
/api/fulfillment-orders/:fulfillmentOrder/move

Pre-submit warehouse re-route. Relocates the WHOLE fulfillment order to a new warehouse: every line on the FO has its sales-order-line warehouse moved and its committed stock re-allocated at the target, and the FO itself is re-pointed there (the shipping provider follows the warehouse). It is the FO-level equivalent of moving each line individually. To move a single line instead, use the per-line move on the sales order.

Required scope: orders:write

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

Mutability gate. Allowed ONLY when the FO is status=open AND request_status=unsubmitted. Once the FO is handed to a provider (anything beyond unsubmitted) the warehouse decision is frozen — returns 409.

Backorder, warn-first. A target short on stock does NOT block the move: the shortfall backorders (Planned) and is evicted off the FO so it holds only shippable lines (a wholly-uncovered FO is deleted). Because that quietly backorders, an un-acknowledged move that would backorder returns 409 with requires_acknowledgement: true and a coverage object instead of committing — call GET .../move-preview (or read that coverage) to warn the user, then resend with acknowledge_backorder: true. Blemished products can't backorder; their shortfall is flagged as blemished_shortfall in the coverage.

Body fields:

  • warehouse_id (required, integer, must exist) — new destination warehouse.
  • acknowledge_backorder (optional, boolean, default false) — set true to proceed when the move would backorder one or more lines.
  • reason (optional, string, max 1000) — free-text note for the audit trail.

Merge into an existing fulfillment order at the target. If the target warehouse already holds an open + unsubmitted fulfillment order for the same sales order (for example, a line was re-routed there earlier), the moved fulfillment order is merged into it rather than left beside it. The response is then the surviving sibling — its id differs from the one in the path, it carries the lines of both, and it keeps its own requested shipping details; the fulfillment order named in the path is deleted. A sibling that has been submitted or rejected is never merged into. Call GET .../move-preview first: merge_into_fulfillment_order_id tells you whether this will happen.

Required permission: fulfillment_orders.update (Fulfillment Orders → Edit) and fulfillment_orders.index (Fulfillment Orders → View). A token also needs its orders scope; the owner needs these role permissions.

Request​

Responses​

OK

Response Headers
    Content-Type