Orders API reference
The HTTP surface for creating and reading orders.
Create an order
POST/ordersBearer token
Submit a cart and create a new order.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| idempotency-key | header | string | Safe-retry key |
Request body
| Field | Type | Description |
|---|---|---|
| items required | Item[] | Line items |
| coupon | string | Optional discount code |
Responses
| Status | Description | |
|---|---|---|
| 201 | Order created | |
| 400 | Invalid cart | |
| 401 | Missing or invalid token | |
Example request
{ "items": [{ "sku": "A1", "qty": 2 }] }
Example response
{ "id": "ord_123", "status": "pending" }
Request flow
SEQUENCE
Legendcallresponsethe answer the caller getsactive
Data touched
ER
Legend#primary key→foreign key1 / Ncardinalityaggregate root
Status codes
| Code | Meaning | When |
|---|---|---|
| 201 | Created | Order accepted |
| 400 | Bad request | Cart failed validation |
| 401 | Unauthorized | Missing or invalid token |