How we bill each event exactly once

Description and use

The system guarantees single‑charge per event by combining the meter update and idempotency checkpoint into one DynamoDB transaction and using a first‑writer claim to avoid double billing.

Problem

Ensuring idempotent billing for each event in a distributed system where the meter, ledger, and storage live in separate databases, so that crashes or retries do not cause double‑charging or lost charges.

Outcome

By consolidating the meter update and idempotency checkpoint into a single DynamoDB transaction and using a first‑writer‑wins claim, the system guarantees exactly‑once billing even in the face of crashes or retries, eliminating double‑charges and lost charges.

Workflow

• 1. Event arrives at the front door and is enqueued (returns 202).
• 2. Queue worker claims the event with a conditional PutItem (attribute_not_exists(pk)).
• 3. Worker performs a TransactWriteItemsCommand that: a) updates the free‑usage counter with a conditional expression, and b) sets billingAcceptedAtMs on the ledger item if status is INSERTING.
• 4. If the transaction succeeds, the event is archived to S3 and the analytics row is written to ClickHouse.
• 5. On retry, the worker reads the ledger; if billingAcceptedAtMs exists, it skips re‑billing and recovers the event data.
• 6. All steps are idempotent and recoverable, ensuring exactly‑once billing.

Evidence

The meter and the checkpoint cannot diverge because they were never two writes.

Source

attribute_not_exists(pk) makes this a first-writer-wins gate for all time.

Source