Skip to main content

Record Shipment

POST 
/api/fulfillment-orders/:fulfillmentOrder/record-shipment

Record a REAL shipment (one SalesOrderFulfillment) against this fulfillment order — the operator fallback for the intent/execution split. A fulfillment order is the provider's order; shipments come back as 1..N SalesOrderFulfillments over time.

Body:

  • lines (optional array): per-line shipped quantities {sales_order_line_id, quantity}. OMIT to ship the full remaining_quantity of every line. Each quantity is clamped to the line's remaining_quantity.
  • tracking_number (optional), carrier (optional), shipping_method (optional).
  • shipped_at (optional date, Y-m-d): the provider's actual shipped date — becomes the SOF fulfilled_at / COGS accounting date (defaults to today if omitted).
  • provider_shipment_id (optional): the provider's shipment identifier — idempotent dedup (a re-recorded id never duplicates the SOF).

Side effects: creates the SalesOrderFulfillment (+ inventory movements, COGS, fulfilled_quantity), decrements each line's remaining_quantity, and advances the FO lifecycle: Open → Incomplete ("Partially shipped") → Closed (fully shipped).

Returns the FO with its updated lines + shipments. 422 if there is nothing left to ship or the report exceeds remaining quantity.

Authentication: Requires Bearer token.

Request​

Responses​

OK

Response Headers
    Content-Type