DOCUMENTAPI · v1

Orders API reference

The HTTP surface for creating and reading orders.

Create an order
01 · API endpoint
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" }
Orders API reference2 / 5
Request flow
02 · Sequence
SECTION 02 · Sequence
SEQUENCE
Sequence diagram: 3 messages between 3 actorsClientOrders APIDatabase1POST /orders2INSERT order3201 Created
Legendcallresponsethe answer the caller getsactive
Orders API reference3 / 5
Data touched
03 · Entity model
SECTION 03 · Entity model
ER
Entity relationship diagram: 2 entitiesN1AGGREGATE ROOTorders#iduuidstatustextENTITYorder_items#iduuid→order_iduuidskutextBELONGS TO
Legend#primary key→foreign key1 / Ncardinalityaggregate root
Orders API reference4 / 5
Status codes
04 · Comparison
SECTION 04 · Comparison
CodeMeaningWhen
201CreatedOrder accepted
400Bad requestCart failed validation
401UnauthorizedMissing or invalid token
Orders API reference5 / 5
1 / 5
Document