Overview
A fulfillment order (FO) is the downstream record that tells a warehouse or fulfillment channel what to pick, pack, and ship for a given sales order. Creating one requires the sales order to be posted first. Once created, you confirm (push) the FO to your fulfillment channel so it can be acted on.
Luminous supports three paths:
- Automatic daily generation — the system creates FOs on its own.
- Manual generation from the UI — you trigger generation for selected orders.
- API generation — your integration calls an endpoint directly.
Prerequisites
- The sales order must be posted (not in draft or purgatory).
- At least one Fulfillment Priority List must be configured (Settings → Smart Fulfillment). Without a priority list, the system cannot determine which warehouse should fulfill the order.
- The Smart Fulfillment settings in System Settings control whether FOs are created even when stock is insufficient (Always Create), whether the system tries to consolidate all items into one warehouse first (Consolidate Orders), and the minimum stock percentage threshold for splitting (Partial Fulfillment Threshold).
Path 1 — Automatic daily generation
Luminous runs an automatic job each day that scans posted sales orders from the past two days that do not yet have fulfillment orders and generates them. No manual action is required. You can monitor results in the Fulfillment Orders grid.
If you also enable the Auto-Push feature (via channel integration settings), FOs are pushed to the fulfillment channel automatically after a configurable delay (for example, 15 minutes after creation).
Path 2 — Manually generate from the UI
- Go to Operations → Sales Orders.
- Select one or more posted sales orders using the row checkboxes.
- Open the Bulk Actions menu and choose Auto Generate Fulfillment Orders.
- A dialog opens listing the selected orders with a Pending status. Orders that already have fulfillment orders appear in a separate Excluded section.
- Click Generate. The dialog processes orders in batches of 10, updating each row to Processing → Success or Failed.
- If any orders fail (for example, due to insufficient stock or a missing priority list), a Retry Failed button appears. Fix the underlying issue (check stock levels, verify your priority list is set up) and retry.
- Close the dialog. The grid refreshes to show the newly created FOs.
Path 3 — API: auto-generate fulfillment orders
Use the internal V2 endpoint to trigger generation for one or more sales orders from your integration:
POST /v2/api/admin/orders/fulfillment-orders/auto-generate-for-sales-orders
Request body:
{
"salesOrderIds": [1234, 5678]
}
The endpoint applies the same Smart Fulfillment rules as the UI. It returns a result for each order indicating success or an error message. You can include multiple salesOrderIds in a single call.
After creation — pushing (confirming) the FO to a fulfillment channel
Creating a fulfillment order puts it in Pending status. To confirm it with the warehouse or WMS, you push it:
From the UI
- Open the Fulfillment Orders grid (from the sales order detail page or the main Fulfillment Orders page).
- Find the FO row and open its action menu (⋮).
- Choose Push to Fulfillment Channel.
- This option is available when the FO has not yet been pushed, or when its status is Action Required.
- Confirm the push in the dialog that appears.
You can also bulk-push by selecting multiple FO rows and using the toolbar action.
Automatic push (optional)
If your fulfillment channel is configured with an Auto-Push Delay (for example, 15 minutes), Luminous will push FOs automatically after that delay without any manual step.
Recording a shipment (marking an FO as shipped)
Once the warehouse ships the order, Luminous expects a shipment record to close the loop.
From the UI
In the FO action menu, choose Create Shipment and fill in the tracking number, carrier, and line items.
Via API — shipment scoped to a fulfillment order
This is the preferred API path when you have the FO id, because it guarantees the shipment is associated with the correct FO in Luminous:
POST /external/api/v1/fulfillment-orders/{fulfillmentOrderId}/shipments
Minimum required fields:
| Field | Notes |
|---|---|
ship_date | Format YYYY-MM-DD |
tracking_number | Carrier tracking number |
carrier_code | Carrier code (e.g. ups, fedex) |
ship_to | Ship-to address object |
weight | Weight with value and units |
dimensions | Package dimensions with units, length, width, height |
items | Array of line items; each needs product_id, order_item_id, quantity, and unit_price |
The sales order is resolved automatically from the FO — you do not need to pass it separately.
Idempotency: if a shipment with the same tracking number and carrier code already exists for the order, it is returned as-is and linked to the FO. No duplicate is created.
Via API — shipment scoped to a sales order (without an FO id)
If you do not have the FO id, you can create the shipment under the sales order directly:
POST /external/api/v1/sales-orders/{salesOrderId}/shipments
The body shape is identical. You may optionally pass fulfillment_order_id in the body to associate the shipment with a specific FO — the FO must belong to the same sales order, otherwise the request is rejected.
Troubleshooting
| Symptom | Likely cause |
|---|---|
| No FOs generated | Sales order is not posted, or no fulfillment priority list is configured |
| All items go to one FO when you expected splits | Allow Line Item Splitting is off in Smart Fulfillment settings, or the channel is not configured to split by estimated_ship_date |
| FO created but stock shows shortage | Always Create is enabled; the FO is created anyway but the warehouse may not have enough inventory |
| Push fails with an error status | Check the FO's Error status in the grid; fix the underlying integration issue and reset the status to retry |
422 from shipment API | Verify order_item_id values exist and belong to the correct sales order; ensure required fields (ship_date, tracking_number, carrier_code) are present |