Place Order
Create an order from a cart and complete the checkout process.
Authentication
This query supports both authenticated customers and guest users:
- Authenticated customers: Provide a valid customer authentication token in the
Authorizationheader. Obtain this token via the Customer Login API. - Guest users: Provide the Guest Cart Token
cartTokenobtained from the Create Cart mutation.
Authorization: Bearer <accessToken>Response
| Field | Type | Description |
|---|---|---|
id | ID | The cart id the order was placed from (numeric — this is an action result, not a fetchable IRI; use orderId for the created order). |
orderId | String | The created order id — only set on the on-site path. null when a payment redirect is required (the order is created after the gateway confirms). |
redirect | Boolean | true when the payment method needs the shopper sent to a payment page before the order exists. |
redirectUrl | String | The payment page to open when redirect is true; null otherwise. |
success | Boolean | true when the call succeeded — either the order was placed or a redirect is required. Order-placement failures are returned in errors[], not here. |
message | String | Human-readable result — "order placed", or an explanation that the shopper must be redirected to complete payment. |
Two outcomes
This mutation has two success shapes — branch on redirect:
redirect: false(cash-on-delivery, money-transfer) — the order exists; readorderId.redirect: true(stripe, payu, phonepe, razorpay, paypal) — no order yet.orderIdisnull; send the shopper toredirectUrlto pay. The order is created when the gateway returns to your success URL.messageexplains this so a client that only checks the payload knows why there is no order id.
On a genuine failure (empty cart, missing address/shipping/payment, suspended account, minimum-order not met) the mutation returns errors[] with the exact reason and checkoutOrder is null.
Before the order can be placed
Every step of the checkout must be complete. The mutation fails with errors[] and a null payload when any of them is outstanding:
| Requirement | Satisfied by |
|---|---|
| The cart holds at least one item | Add to Cart |
| A billing address is set | Set Checkout Address |
| A shipping address is set, for a cart with shippable items | Set Checkout Address |
| A shipping method is selected | Set Shipping Method |
| A payment method is selected | Set Payment Method |
Stock is re-checked at this point as well, so an item that sold out while the shopper was in checkout fails the call even though every step was completed.
A coupon is not a prerequisite. An invalid or expired one blocks the order, but placing an order without any coupon is the normal case.
Order status after placing
A newly placed order is pending, or pending_payment while a redirect gateway completes. It then moves through the store's own workflow:
| Status | Meaning |
|---|---|
pending | Order created and awaiting processing. |
pending_payment | Awaiting payment confirmation from the gateway. |
processing | Payment confirmed and the order is being prepared. |
completed | Fully invoiced and shipped. |
canceled | Canceled before fulfilment. |
closed | Closed after a refund. |
fraud | Flagged by the store as fraudulent. |
What happens on success
- The cart is emptied and its token stops resolving.
- The order confirmation email is sent to the shopper.
- Stock is decremented for every ordered item.
- The shopper can track the order through Get Customer Orders.
On a redirect payment none of this happens yet — the cart survives until the gateway returns and the order is actually created.