Orders — Order events history

binding spec data-contracts/orders-events.odcs.yaml @ 1.2.0 — the spec of record. It states what must be; implementations converge on it, never the reverse.

Enforced by

check:version — any change must bump the artifact and service versions; a silent edit fails CI
datacontract-cli validation
Spectral house rules for attribute and value naming

Version history

Version	First released	Service version
`1.2.0`	2026-08-24	2.1.0
`1.1.0`	2026-08-23	2.0.0
`1.0.0`	2026-08-23	1.1.0

Consume it

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

Status: active · Domain: Commerce ·Data product: orders

Purpose

Append-only historical record of the Order aggregate's events. One row per event, mirroring the AsyncAPI payloads on orders.placed.v2 and orders.cancelled.v2 field for field - the stream is ephemeral, this table is the record.

Usage

Order lifecycle analytics, audit, and replay/backfill for downstream consumers that joined after the fact. Not a source for current order state - use the orders service API for that.

Limitations

Delivery upstream is at-least-once; rows are deduplicated on the CloudEvents envelope id, so exactly one row per event. Events land within minutes but ordering across event types is only guaranteed per order_id.

Schema

erDiagram
    order_placed_events {
        string event_id PK
        string event_type
        string event_source
        date event_time
        string order_id UK
        string customer_id
        date placed_at
        integer total_pence
    }
    order_cancelled_events {
        string event_id PK
        string event_type
        string event_source
        date event_time
        string order_id UK
        date cancelled_at
        string reason
    }

order_placed_events — One row per OrderPlaced event on orders.placed.v2.

Field	Type	Required	Key	Constraints
`event_id`	string (uuid)	yes	primary key, unique	—
`event_type`	string (text)	yes	—	—
`event_source`	string (text)	yes	—	—
`event_time`	date (timestamp)	yes	—	—
`order_id`	string (uuid)	yes	unique	—
`customer_id`	string (uuid)	yes	—	—
`placed_at`	date (timestamp)	yes	partition	—
`total_pence`	integer (bigint)	yes	—	≥ 0

order_cancelled_events — One row per OrderCancelled event on orders.cancelled.v2.

Field	Type	Required	Key	Constraints
`event_id`	string (uuid)	yes	primary key, unique	—
`event_type`	string (text)	yes	—	—
`event_source`	string (text)	yes	—	—
`event_time`	date (timestamp)	yes	—	—
`order_id`	string (uuid)	yes	unique	—
`cancelled_at`	date (timestamp)	yes	partition	—
`reason`	string (text)	yes	—	one of customer_request, payment_failed, out_of_stock

SLA

latency: 15m

Ownership & support

team-commerce (owner)
slack: #orders-support