Commerce
Orders
Order statuses, changes after placement, returns, exchanges, and claims.
An order is created when a cart is completed or a draft order is converted. After that, every change goes through an order change, so the order keeps a version history.
Statuses
An order has three separate statuses.
| Field | Values |
|---|---|
status | pending, completed, requires_action, canceled, archived, draft |
payment_status | not_paid, awaiting, authorized, partially_authorized, captured, partially_captured, partially_refunded, refunded, canceled, requires_action |
fulfillment_status | not_fulfilled, partially_fulfilled, fulfilled, partially_shipped, shipped, partially_delivered, delivered, canceled |
Show buyers the payment and fulfillment statuses. status is mostly for the merchant.
Reading orders
- Store routes return only the signed-in customer's own orders: list and get.
- An order placed by a company employee is linked to their company. There is no route yet for listing a whole company's orders.
display_idis the human-readable order number. Useidin API calls.
Changing an order
All of these run in the same pattern: start a change, add items or shipping to it, then request or confirm it. Until confirmed, nothing on the order changes and you can preview the result with Order preview. An order has at most one active change at a time.
| Change | What it does | Started by |
|---|---|---|
| Order edit | Add, remove, or change quantities of items. | Merchant |
| Return | Items come back, usually for a refund. | Merchant, or buyer with Create return |
| Exchange | Items come back and different items go out. | Merchant |
| Claim | Items arrived damaged, wrong, or missing. Type refund or replace. | Merchant |
- A change can leave an amount owed either way. The order's
summaryshows it; collect the difference or refund. - Returns need a return shipping option (
return_shipping.option_id). See Fulfillment. - Receiving a return puts the items back in stock at the chosen location.
- Buyers give a return reason per item.
Other actions
- Cancel: only when every fulfillment is canceled and the order isn't completed. Releases reservations, cancels uncaptured payments, and refunds captured ones.
- Create a fulfillment and mark it shipped. See Fulfillment.
- Transfer an order to another customer, for example a guest order to a new account.