BLOG
Designing Idempotent Billing APIs at Scale
Why every charge, refund, and usage event needs an idempotency key — and how we built ours.
Engineering
· 9 min read

Ava Reyes
· Product Marketing

In billing, a duplicated request isn’t a glitch — it’s a double charge. Networks time out, clients retry, and queues redeliver. Idempotency makes all of that safe.
Keys on every write
Every request that creates a charge, refund, or usage record accepts an idempotency key. The first request does the work; every repeat returns the stored result.
Store the response, not just the key
Saving only the key tells you a request happened. Saving the full response lets retries get exactly the same answer, including errors.
A retry should be boring. Same input, same output, no side effects.
Expire with care
Keys live long enough to cover realistic retry windows — we keep them for 24 hours — and usage events are deduplicated by event ID for the whole billing period.



