Idempotency key
A unique identifier attached to an event so a duplicate delivery — from a retry, for example — is recognized and ignored rather than double-counted.
An idempotency key is a unique identifier attached to a usage event so that if the same event is delivered more than once — most often because a network call timed out and the sender retried it — the duplicate delivery is recognized and dropped instead of being counted, and billed, twice.
It matters because network failures are a certainty at scale, not an edge case: a request can succeed on the server but time out on the client before the response arrives, and the client's only safe option is to retry. Without a way to tell 'the same event, sent again' apart from 'a new event,' that retry becomes a double charge.
In practice, the caller generates a key, often a UUID, once per logical event and sends it with every attempt to deliver that event. The receiving ledger checks incoming keys against what it's already recorded; a key it's seen before is a no-op, and only a genuinely new key gets appended and aggregated.
The common pitfall is generating a new key on every retry attempt instead of reusing the same one — that defeats the entire mechanism, since the ledger has no way to recognize the retries as duplicates of the original event. The key has to be generated once, at the moment the event is created, and reused for every delivery attempt of that same event.