How do I create and confirm a fulfillment order from an existing sales order in Luminous, including the API request sequence?

Overview

A fulfillment order (FO) tells your warehouse or fulfillment channel exactly what to pick, pack, and ship for a given sales order. Luminous can create FOs automatically (using your warehouse priority lists and stock data) or you can trigger the process manually — both from the UI and via the API. Once an FO exists you "confirm" it by pushing it to your fulfillment channel.

Prerequisites

Before an FO can be created the following must be true:

Requirement	Why it matters
Sales order is posted	Unposted orders are skipped by the auto-generate engine.
At least one Fulfillment Priority List is configured	The engine uses these lists to decide which warehouse(s) to assign.
The products have available stock in at least one warehouse	Unless your Smart Fulfillment setting Always Create is enabled, orders with zero available stock will not generate an FO.
A fulfillment channel is set up	Required if you intend to push the FO downstream.

Step 1 — Create the fulfillment order

Via the UI

Go to Operations → Sales Orders.
Find the posted sales order you want to fulfill and open it (row ⋮ menu → View Sales Order).
Open the Fulfillment Orders tab, click its Actions menu and select Auto Generate Fulfillment Orders.
A confirmation dialog opens. Confirm to start the process.
Luminous runs the auto-generation engine, which:
- Separates any items flagged Fulfill Separately into their own FOs.
- Groups remaining items and tries to consolidate them into a single warehouse (if Consolidate Orders is enabled in Smart Fulfillment Settings).
- Falls back to splitting items across warehouses if consolidation fails and Allow Line Item Splitting is on.
- Respects the Partial Fulfillment Threshold (minimum stock percentage) before assigning to a warehouse.
- Optionally creates the FO even with insufficient stock if Always Create is on.

The resulting FO(s) appear in the Fulfillment Orders tab on the sales order detail page.

Via the API

Use the internal V2 endpoint. This is the same endpoint the UI calls.

Request

POST /v2/api/admin/orders/fulfillment-orders/auto-generate-for-sales-orders
Content-Type: application/json

{
  "salesOrderIds": [12345]
}

Body field	Type	Notes
`salesOrderIds`	array of integers	One or more sales order IDs.
`skipStatusCheck`	boolean (optional)	Defaults `true`. Set `false` to enforce posted-status validation.
`fulfillmentOrderStatus`	string (optional)	Override the initial FO status. Allowed values: `pending`, `planned`, `awaiting_shipment`, `shipped`. Omit to use your tenant default.

The response contains a per-order result array indicating success or any shortage/error details for each ID.

Step 2 — Review the created fulfillment order(s)

To list FOs for a sales order via the External V1 API:

GET /external/api/v1/fulfillment-orders?sales_order_id[eq]=12345

Each FO object includes:

id — the fulfillment order ID you'll use in the next step.
order_status — e.g. pending, awaiting_shipment.
warehouse_group_id — which warehouse group was assigned.
ship_by_date — auto-populated when splitting by estimated ship date.

Step 3 — Confirm (push) the fulfillment order to your channel

"Confirming" a fulfillment order means pushing it to your downstream fulfillment channel (e.g. a WMS like TrackStar). This is what triggers the warehouse to start picking.

Via the UI

Open the sales order and go to the Fulfillment Orders tab.
Find the FO you want to confirm.
Click Push to Fulfillment Channel.
Luminous transmits the FO to the configured channel. A success message confirms the push; an error message appears if something went wrong (e.g. a duplicate was detected — see the Reconcile section below).

Via the External V1 API

POST /external/api/v1/fulfillment-orders/{fulfillmentOrderId}/push

No required body fields. Optional:

Field	Type	Notes
`debug`	boolean	When `true`, includes outbound HTTP traffic details in the response under `data.debug`.

Success response (200)

{
  "data": {
    "success": true,
    "message": "Fulfillment order pushed successfully."
  }
}

Failure response (422) — the response also includes a links.reconcile URL you can call if the push failed due to a duplicate order in the destination system.

Optional: Auto-push (no manual push needed)

You can configure a fulfillment channel to push FOs automatically after a set number of minutes. Once enabled, any FO assigned to that channel is pushed automatically without requiring a manual call to the push endpoint. This requires the AUTO_PUSH_FULFILLMENT_ORDERS_SCHEDULED feature flag to be active on your tenant and an autoPushOrderAfterMinutes value set on the channel's integration mapping. Contact your Luminous administrator to configure this.

Complete API sequence at a glance

# 1. Confirm the sales order is posted
GET /external/api/v1/sales-orders/12345

# 2. Auto-generate the fulfillment order
POST /v2/api/admin/orders/fulfillment-orders/auto-generate-for-sales-orders
{ "salesOrderIds": [12345] }

# 3. Find the created FO(s)
GET /external/api/v1/fulfillment-orders?sales_order_id[eq]=12345

# 4. Push (confirm) the FO to the fulfillment channel
POST /external/api/v1/fulfillment-orders/{fulfillmentOrderId}/push

Troubleshooting

Symptom	Likely cause	Fix
No FO was created	Sales order not posted, or no priority list exists	Verify `is_posted = true`; check that a default priority list is configured in Settings → Smart Fulfillment.
FO created but stock shortage reported	Insufficient available stock and Always Create is off	Enable Always Create in Smart Fulfillment Settings, or replenish stock first.
Push returns 422	Duplicate order already exists in the destination WMS	Use the `links.reconcile` URL in the error response to bind the existing remote order.
FO stuck in Error status	Push failed on a previous attempt	Investigate the error, fix the underlying issue, then reset the FO status to retry.