Skip to lesson
Exit
Order-to-Cash, Deep1 / 2

2 min lesson

Usage events: append-only, idempotent, replayable

Work through the cases in "Usage events: append-only, idempotent, replayable", pairing each signal with the move that fits.

Step 1 of 2

Usage events: append-only, idempotent, replayablethe high-volume stream

Usage is the highest-volume table in a consumption business and the one most likely to corrupt revenue if you get it wrong. Three properties are non-negotiable.

Append-only

Events are facts that happened.

Never update or delete; corrections are new compensating events.

Idempotent

Each event carries a stable unique id.

Re-ingesting the same event id is a no-op, so retries cannot double-bill.

Replayable

You can re-run rating over a window from raw events.

Lets you recompute an invoice when a pricing bug is found.

a minimal, idempotent usage event shape
-- raw usage: append-only, dedup on event_id
CREATE TABLE usage_event (
  event_id     text PRIMARY KEY,        -- idempotency key from the producer
  account_id   text NOT NULL,
  meter        text NOT NULL,           -- e.g. 'requests', 'input_tokens'
  quantity     numeric NOT NULL,
  occurred_at  timestamptz NOT NULL,    -- when it happened (for the usage period)
  received_at  timestamptz NOT NULL,    -- when we ingested it (for late-arrival)
  contract_id  text NOT NULL
);

-- a duplicate delivery is a no-op, not a double charge
INSERT INTO usage_event (...) VALUES (...)
ON CONFLICT (event_id) DO NOTHING;
Watch out

Keep occurred_at and received_at as separate columns. The usage period is decided by when the event happened, but late-arrival handling and reconciliation depend on when you got it. Collapsing them into one timestamp is a classic mistake that makes period-close corrections impossible to reason about.