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.
orders:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
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 → Closed (fully shipped). A partially-shipped FO stays open with remaining_quantity > 0 on its lines — the separate in_progress / incomplete partial-shipped statuses were retired in rung 3.
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
- 200
- 401
- 403
- 404
- 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.
Unprocessable Content
Response Headers
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.