DOCUMENTAPI · v1

Orders API reference

The HTTP surface for creating and reading orders.

Create an order

SECTION 01 · API endpoint
POST/ordersBearer token

Submit a cart and create a new order.

Parameters
NameInTypeDescription
idempotency-keyheaderstringSafe-retry key
Request body
FieldTypeDescription
items requiredItem[]Line items
couponstringOptional discount code
Responses
StatusDescription
201Order created
400Invalid cart
401Missing or invalid token
Example request
{ "items": [{ "sku": "A1", "qty": 2 }] }
Example response
{ "id": "ord_123", "status": "pending" }

Request flow

SECTION 02 · Sequence
FLOW
Sequence diagramClientOrders APIDatabase1POST /orders2INSERT order3201 Created

Data touched

SECTION 03 · Entity model
ER
Entity-relationship diagramordersPKiduuidstatustextorder_itemsPKiduuidFKorder_iduuidskutextbelongs to

Status codes

SECTION 04 · Comparison
CodeMeaningWhen
201CreatedOrder accepted
400Bad requestCart failed validation
401UnauthorizedMissing or invalid token