What is a Fulfillment Order?
A Fulfillment Order (FO) is the record Luminous uses to route items from a posted Sales Order to a specific warehouse group and fulfillment channel (such as a third-party logistics provider or an in-house warehouse). Think of it as a "picking and shipping instruction" for a warehouse.
One Sales Order can produce multiple Fulfillment Orders — for example, when items need to ship from different warehouses, when items have different estimated ship dates, or when certain products are flagged to be fulfilled separately.
Fulfillment Order Lifecycle
- Sales Order Posted — The Sales Order arrives and is posted in Luminous.
- Fulfillment Order Created — Luminous creates one or more FOs (automatically or manually).
- Pushed to Fulfillment Channel — The FO is sent to the assigned warehouse or WMS.
- Shipped — The warehouse fulfills the order and returns tracking information.
- FO Marked Shipped — Luminous updates the FO status and records the shipment.
Option A: Auto-Generate a Fulfillment Order
This is the most common path. Luminous can automatically create FOs based on your Smart Fulfillment Settings and Fulfillment Priority Lists.
How auto-generation works
- The system checks which warehouse groups have available stock (on-hand minus pending).
- It respects your Fulfillment Priority Lists — the ordered list of warehouse groups allowed to fulfill each product.
- If Consolidate Orders is enabled, it tries to ship everything from a single warehouse first.
- If stock is spread across warehouses (and Allow Line Item Splitting is on), it can split quantities across multiple FOs.
- Items marked Fulfill Separately on the product always get their own FO.
- If your channel is configured to Split by Estimated Ship Date, items with different ship dates each get their own FO.
Trigger auto-generation from the UI
- Open the Sales Order (it must already be posted).
- Scroll to the Fulfillment Orders tab.
- Click Actions and choose Auto Generate Fulfillment Orders.
- Confirm the prompt — Luminous runs the generation and refreshes the panel.
You can also trigger auto-generation in bulk from the Sales Orders list by selecting one or more posted orders and choosing Auto Generate Fulfillment Orders from the Bulk Actions menu.
Automatic daily run: Luminous also runs auto-generation automatically once a day for any posted Sales Orders from the past two days that do not yet have a Fulfillment Order.
Option B: Create a Fulfillment Order Manually
If you need to create a FO without using the auto-generation engine:
- Open the Sales Order (must be posted).
- Go to the Fulfillment Orders tab.
- Click Actions → Create Fulfillment Order.
- Luminous will check that the order has remaining quantity to fulfill (non-physical and non-inventory lines are excluded).
- Fill in the fulfillment details in the form that appears and save.
Pushing a Fulfillment Order to the Fulfillment Channel
Once a FO exists, it needs to be pushed to the warehouse or WMS before it can be picked and shipped.
Push manually from the UI
- In the Fulfillment Orders tab (on the Sales Order) or from the Fulfillment Orders page (
Operations → Fulfillment Orders), select the FO(s) you want to push. - Click the actions menu and choose Push to Fulfillment Channel.
- Luminous validates eligibility — only FOs that have not been pushed yet, or those in Action Required status, can be pushed.
- Results are shown order-by-order; any failures display a reason.
Auto-push (scheduled)
Your account may be configured to automatically push FOs after a set delay (e.g., 15 minutes after creation). When this is active, new FOs are pushed without manual intervention. Contact your Luminous administrator if you want to adjust the delay or enable this feature for a channel.
Fulfillment Order Statuses
| Status | Meaning |
|---|---|
| Pending | Created, not yet pushed to a channel |
| Action Required | A previous push failed and needs attention |
| Pushed | Successfully sent to the fulfillment channel |
| Shipped | The warehouse has shipped the order |
| Error | Push failed; excluded from future auto-push until reset |
| Cancelled | FO has been cancelled |
Recording a Shipment via the External API
If you are integrating with Luminous over the API, you can record a carrier shipment against a Fulfillment Order directly.
Create a shipment tied to a Fulfillment Order
POST /external/api/v1/fulfillment-orders/{fulfillmentOrderId}/shipments
Minimum required fields:
| Field | Required | Notes |
|---|---|---|
ship_date | Yes | Format: YYYY-MM-DD |
tracking_number | Yes | |
carrier_code | Yes | |
ship_to | Yes | Object with name, street1, city, state, postalCode, country |
weight | Yes | Object with value and units (e.g., ounces) |
dimensions | Yes | Object with units, length, width, height |
items | Yes | Array; each item needs product_id, order_item_id, quantity, unit_price |
The FO's Sales Order is resolved automatically from the FO — you do not pass the Sales Order ID separately. If a shipment with the same tracking number and carrier already exists, the API returns it without creating a duplicate.
Response: 201 Created with the new shipment resource, including warehouse_group_id from the linked FO.
Alternatively: create a shipment on the Sales Order and link it to an FO
POST /external/api/v1/sales-orders/{salesOrderId}/shipments
Pass the optional fulfillment_order_id field in the request body. The FO must belong to the same Sales Order or the request is rejected.
List Fulfillment Orders via API
GET /external/api/v1/fulfillment-orders
Supports filtering by id, order_status, warehouse_group_id, sales_order_id, ship_by_date, and several Sales Order relationship fields (e.g., sales_order.order_number, sales_order.channel_name). Returns paginated results with nested line items and picklist data.
Troubleshooting
No Fulfillment Orders are being generated
- Confirm the Sales Order is posted (unposted orders are skipped).
- Check that a Fulfillment Priority List is configured (at least one default list is required).
- If stock is insufficient and Always Create is disabled, no FO is generated. Enable Always Create in Smart Fulfillment Settings or the channel configuration if you want FOs to be created regardless of stock.
Items are not splitting by estimated ship date
- The channel must be configured with Split by Estimated Ship Date.
- Order items must have
Estimated Ship Datevalues set.
A push fails and the FO shows Error status
- Check the error message on the FO for the specific cause.
- Fix the underlying issue (e.g., address, channel configuration).
- Update the FO status back to a non-Error value, then push again.