Skip to main content

Submit Fulfillment Order to Provider

POST 
/api/fulfillment-orders/:fulfillmentOrder/submit

Transitions request_status from unsubmitted → submitting and stamps submitted_at to the moment of hand-off (NOT when the carrier confirms — see Stage 2 for the carrier-callback flow that flips submitting → submitted/accepted).

Required scope: orders:write

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

Mutability gate. Allowed ONLY when status=open AND request_status=unsubmitted. Violations return 409.

Request body (all fields optional). Submission acts on the WHOLE FO — there are no per-line quantities (split the FO first to dispatch part of it).

  • acknowledge_open_channel_fulfillment (boolean, default false) — double-fulfillment guardrail (F4a). When an still-open sales-channel (Shopify) fulfillment order may yet ship some of this FO's units, an omitted/false submit is refused with 409 carrying requires_acknowledgement: true and a coverage preview. Resubmit with this true to dispatch natively anyway.
  • requested_integration_instance_id (integer|null) — per-FO shipping-provider override; must be a SHIPPING_PROVIDER instance.
  • requested_fulfillment_type (string|null, only manual) — force Manual dispatch (no integration instance).
  • requested_shipping_method_id (integer|null) / requested_shipping_method (string|null) — requested carrier service.
  • requested_ship_date (date|null), requested_metadata (object|null) — optional ship intent bridged onto the SalesOrderFulfillment (notes, fulfillment_sequence, signature_required, veracore_*, isInsured, instructionsForWarehouse).
  • lot_allocations (array|null) — per-line FEFO override for lot-tracked lines: [{ sales_order_line_id, lots: [{ fifo_layer_id, quantity }] }]. Re-validated at dispatch; stale picks fall back to FEFO. Omit for automatic FEFO/FIFO.

Set override_partial_dispatch to true to dispatch a sales order that is only partially fulfillable even when partial dispatch is disabled in fulfillment settings. When it is disabled and the order is not fully fulfillable, the request is refused with 409 and a body code of partial_dispatch_disabled.

Request​

Responses​

OK

Response Headers
    Content-Type