OMS Orders API
Last updated 2026-10-13
Create draft sales orders, query orders, drive the order state machine, and push to WMS.
Create a draft order#
POST /api/oms/orders
{
"customer_id": "<uuid>",
"channel_id": "<uuid>",
"channel_order_no": "AMZ-123",
"merchant_id": "<uuid>",
"warehouse_id": "<uuid>",
"retailer_id": "<uuid>",
"carrier_code": "UPS",
"service_code": "GROUND",
"currency": "USD",
"ship_to": { "name": "…", "address": "…", "city": "…", "state": "…", "postal": "…", "country": "US", "phone": "…" },
"discount": 0,
"shipping_fee": 8.5,
"tax": 0,
"required_ship_date": "2026-10-20",
"note": "…",
"lines": [
{ "product_id": "<uuid>", "qty": 10, "price": 12.9 }
]
}
// -> data.order_no = "SO-YYYYMMDD-####", status = "draft"Query orders#
GET /api/oms/orders?statuses=confirmed,allocated&channel_id=<uuid>&q=AMZ-123&created_from=2026-10-01&page=1&page_size=20
// filters: status (single) | statuses (comma-separated) | channel_id | created_from/to (ISO) | q (order_no / channel_order_no / customer fuzzy)
GET /api/oms/orders/<id>
// detail incl. lines, customer, channel; wms_shipments = all linked WMS shipments (no/status/warehouse/carrier/tracking/split flag)Order state machine#
PATCH /api/oms/orders/<id>
{ "action": "submit" } // draft -> pending_review
{ "action": "approve" } // pending_review -> confirmed (ATP check)
{ "action": "allocate", "warehouse_id": "<uuid>" } // confirmed -> allocated
{ "action": "release", "ship_mode": "parcel" } // allocated -> released
{ "action": "fulfill" } // released -> fulfilled
{ "action": "partial_fulfill" }
{ "action": "deliver" }
{ "action": "cancel" } // only before released
// illegal transition -> 400; draft edit mode: { "fields": {…}, "lines": […] } (draft only)- approve runs an ATP check (wms_sync mode reads WMS inventory balance; standalone reads OMS inventory).
- release requires ship_mode and creates allocation lines (event sales_order.released).
Push to WMS#
POST /api/oms/orders/<id>/push-to-wms
{ "warehouse_id": "<uuid>", "ship_mode": "parcel" } // both optional
// order status must be confirmed | allocated; result: released + WMS shipment created at commit (inventory locked)push-to-wms only works in wms_sync inventory mode; standalone (oms_standalone) orders are rejected with 400 NOT_WMS_SYNC. After the push, WMS drives the shipment: commit → picking → picked → packed → shipped (with tracking) → delivered, and each transition is mirrored back to OMS events in real time; OMS skips the shipped state — shipped on WMS writes OMS fulfilled.