Place Order

Create an order from the shopping cart. This completes the checkout process.

Endpoint

POST /api/shop/checkout-orders

Request Headers

Header	Required	Description
Content-Type	Yes	application/json
X-STOREFRONT-KEY	Yes	Your storefront API key
Authorization	Yes	Bearer token (customer login required)

Request Body

The address, shipping method, and payment method are set on the cart in the preceding checkout steps, so place-order takes an empty body:

{}

Response Fields (201 Created)

Field	Type	Description
id	integer	The cart id the order was placed from (not the order id).
cartToken	string	The cart token.
orderId	string	The created order id — only set on the on-site path; null when a payment redirect is required.
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 — order placed or redirect required. Failures return a 4xx with the reason, not success: false.
message	string	Human-readable result — "order placed", or an explanation to redirect the shopper to complete payment.

Two outcomes — branch on redirect

• redirect: false (cash-on-delivery, money-transfer) — the order exists; read orderId.
• redirect: true (stripe, payu, phonepe, razorpay, paypal) — no order yet. orderId is null; send the shopper to redirectUrl to pay. The order is created when the gateway returns to your success URL. message explains this.

On a genuine failure (empty cart, missing address/shipping/payment, suspended account, minimum-order not met) the endpoint returns a 4xx with the exact reason in the error body — it does not return success: false.

Order Status Values

A newly placed order starts at pending, or processing once payment is confirmed. The full set a storefront can see is listed on Get Customer Orders.

Prerequisites

Each step writes to the cart, and place-order reads what they left behind. They must run in this order:

1. A cart with at least one item — otherwise Cart is empty.
2. A billing address, and a shipping address when the cart holds shippable items — otherwise Billing address is required.
3. A shipping method, for a cart with shippable items.
4. A payment method.

Every failure is reported as a 500 with the reason in detail, not as a 4xx and not as success: false. Read detail to know which step is missing.

After the Order Is Placed

• The cart is emptied and its token can no longer be used for checkout.
• The order confirmation email goes out to the address captured at checkout.
• The order appears in Get Customer Orders for a logged-in shopper. A guest order is not listed there — keep the returned orderId client-side.
• The invoice is created by the store, not at checkout, so Get Customer Invoices may be empty right after placing.

Use Cases

• Finish a guest checkout — the whole flow works with the cart token alone; capture orderId from the response, since a guest cannot look the order up afterwards.
• Gateway checkout — when redirect is true, hand the shopper to redirectUrl and wait for the gateway to return; do not treat the missing orderId as a failure.

Best Practices

• Branch on redirect before reading orderId — on the redirect path there is no order yet and orderId is null.
• Read detail on a failure, not the status code — every missing prerequisite is a 500, so only the message identifies which step to send the shopper back to.
• Store orderId for guests immediately — there is no guest order-lookup endpoint.
• Do not retry blindly after a success — the cart is emptied, so a second call fails with Cart is empty rather than duplicating the order.

Related Resources

• Get Cart — read the current items and recalculated totals
• Set Shipping Address — the same call with a separate delivery address
• Set Billing Address — save both checkout addresses in one call
• Set Shipping Method — save the chosen rate on the cart
• Set Payment Method — save the chosen payment method on the cart
• Get Customer Orders — the customer's order history