Commerce
Draft orders
Orders a merchant builds for a customer, then places.
A draft order is an order that isn't placed yet. A merchant builds it on admin routes, then converts it into a real order. Buyers can't see draft orders on store routes.
B2B use
- Manual and phone orders: a sales rep enters an order for a buyer who emailed or called.
- Negotiated prices: the merchant can set a line's
unit_priceby hand, unlike a cart, which always reprices.
Lifecycle
| Step | Call |
|---|---|
| 1. Create | POST /admin/draft-orders with region_id, email or customer_id, and optional items, addresses, and sales_channel_id. |
| 2. Start an edit | POST /admin/draft-orders/{id}/edit |
| 3. Change it | Add items, shipping methods, or promotions to the edit. |
| 4. Confirm the edit | POST /admin/draft-orders/{id}/edit/confirm, or cancel it. |
| 5. Convert | POST /admin/draft-orders/{id}/convert-to-order |
Steps 2 to 4 repeat as often as needed. Changes made in an edit apply to the draft only when you confirm.
Rules
- A draft order holds no stock. Stock is checked and reserved when it is converted, so conversion can fail if stock ran out.
- Converting recalculates tax, sets the order's status to
pending, and sends the sameorder.placedevent as a checkout. Integrations need no draft-specific path. - Converting doesn't take payment. Collect it afterwards on the order: create a payment collection for the outstanding amount, or mark it as paid when paid offline. See Payments.
- Items added to a draft order are priced with the customer's groups, so company prices apply unless you set
unit_price. - Converting skips the company checkout checks (the
shoppermission and an active company), which run only when a cart is completed. The order is still linked to the buyer's company when it is placed. - Delete a draft you no longer need. A converted draft is an order and can't be deleted.