Commerce
Carts and checkout
From an empty cart to a placed order.
A cart collects items, addresses, a shipping method, and a payment session. Completing it places an order. Every call below needs the publishable API key; send the customer's token too when they are signed in.
The checkout flow
| Step | Call |
|---|---|
| 1. Create the cart | POST /store/carts with region_id. Store the cart ID on the client. |
| 2. Add items | POST /store/carts/{id}/line-items with variant_id and quantity. |
| 3. Set email and addresses | POST /store/carts/{id} |
| 4. Pick shipping | List options with cart_id, then add a shipping method. |
| 5. Start payment | Create a payment collection for the cart, then a payment session with a provider from the region. |
| 6. Complete | POST /store/carts/{id}/complete |
curl -X POST http://localhost:9000/store/carts/cart_.../complete \
-H "x-publishable-api-key: pk_..." \
-H "Authorization: Bearer <customer token>"Rules
- The cart's region sets its currency. Changing the region reprices every line.
- Prices are recalculated on every change, from the current prices and price lists. You can't set a line price from the store.
- Only variants that are in the cart's sales channel and in stock (or allow backorders) can be added. See Inventory.
- A cart created by a signed-in customer belongs to them. To attach a guest cart after sign-in, call Set cart customer.
- Changing items or the region after step 5 can change the total. Create the payment session again before completing.
- Apply discount codes with Add promotions. See Promotions.
Completing
Completion creates the order, then reserves stock (along with linking the order, counting promotion usage, and sending order.placed), then authorizes payment. If anything fails, nothing is kept.
- Success returns
{ "type": "order", "order": { ... } }. Clear the stored cart ID. - A payment that fails or needs more steps returns
200with{ "type": "cart", "cart": { ... }, "error": { ... } }. Show the error and let the buyer retry. - Other failures, such as a missing shipping method or a rule check, return a normal error.
- A second complete call while the first is still running returns
409.
Company carts
A cart created by a company employee is linked to their company, and checkout adds company rules on top of the ones above. See Company checkout.