Orders — API contract

binding spec openapi/orders.openapi.yaml @ 3.2.0 is the spec of record. It states what must be; implementations converge on it, never the reverse.

Enforced by

• any change must bump the artifact and service versions (check:version); a silent edit fails CI
• a breaking change must take a major version (check:compat)
• Spectral lint, house naming rules included
• Microcks contract tests hold mocks and implementations to these operations

Version history

Version	First released	Service version
3.2.0	2026-09-09	3.3.0
3.1.0	2026-08-30	3.2.0
3.0.1	2026-08-29	3.1.0
3.0.0	2026-08-27	3.0.0
2.1.0	2026-08-23	1.0.0

Consume it

• Agents, over MCP: get_artifact('orders', 'openapi/orders.openapi.yaml')
• Raw spec: openapi/orders.openapi.yaml
• Implementations pin the release tag orders/v3.4.0 in their contracts.lock and fetch read-only; the full loop is on Drive an implementation.

Operations

POST/orders · placeOrder

Command — Place an order.

Accepts an order for the given customer and lines. On success the order is persisted and an OrderPlaced event is guaranteed to be published - never one without the other.

Parameter	In	Type	Required
Idempotency-Key	header	string	optional

Request body

Field	Type	Required	Constraints
customer_id	string (uuid)	required	—
lines	array	required	min 1 item(s)
lines[].sku	string	required	—
lines[].quantity	integer	required	≥ 1
lines[].unit_price_pence	integer	required	≥ 0

Responses

Status	Meaning
201	Order accepted; an OrderPlaced event will be published.
400	Invalid order - no lines, a line quantity below 1, a negative unit_price_pence, or a line missing its sku.
409	Idempotency-Key already used with a different body.

201 body

Field	Type	Required	Constraints
order_id	string (uuid)	required	—
customer_id	string (uuid)	required	—
status	string	required	one of placed, paid, cancelled
total_pence	integer	required	≥ 0

Examples (Microcks fixtures)

placed

Request

{
  "customer_id": "22222222-2222-2222-2222-222222222222",
  "lines": [
    {
      "sku": "SKU-001",
      "quantity": 2,
      "unit_price_pence": 1250
    }
  ]
}

Response 201

{
  "order_id": "11111111-1111-1111-1111-111111111111",
  "customer_id": "22222222-2222-2222-2222-222222222222",
  "status": "placed",
  "total_pence": 2500
}

GET/orders/{order_id} · getOrder

Query — Fetch an order.

Returns the order's current state by its id.

Parameter	In	Type	Required
order_id	path	string (uuid)	required

Responses

Status	Meaning
200	The order.
404	No such order.

200 body

Field	Type	Required	Constraints
order_id	string (uuid)	required	—
customer_id	string (uuid)	required	—
status	string	required	one of placed, paid, cancelled
total_pence	integer	required	≥ 0

Examples (Microcks fixtures)

placed

Response 200

{
  "order_id": "11111111-1111-1111-1111-111111111111",
  "customer_id": "22222222-2222-2222-2222-222222222222",
  "status": "placed",
  "total_pence": 2500
}

not_found

Response 404

{
  "error_code": "order_not_found",
  "message": "No order 99999999-9999-9999-9999-999999999999"
}

Full rendered contract