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

Ava Reyes

· Product Marketing

Designing Idempotent Billing APIs at Scale

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.

Get the Billing Brief.

Pricing, RevOps, and product news — one email a month.

RECURA

Billing infrastructure built for modern SaaS businesses.

All systems operational

Copyright © 2026 Recura. All rights reserved.

English (US)

Get the Billing Brief.

Pricing, RevOps, and product news — one email a month.

RECURA

Billing infrastructure built for modern SaaS businesses.

All systems operational

Copyright © 2026 Recura. All rights reserved.

English (US)

Get the Billing Brief.

Pricing, RevOps, and product news — one email a month.

RECURA

Billing infrastructure built for modern SaaS businesses.

All systems operational

Copyright © 2026 Recura. All rights reserved.

English (US)

Create a free website with Framer, the website builder loved by startups, designers and agencies.