Idempotency
Designing an action so that doing it twice has the same effect as doing it once, which protects money and messages from retries.
Updated October 2026 · with examples from our own builds
What does idempotency mean in practice?
Networks retry, users double-tap and payment providers resend events. An idempotent operation notices it has already done this exact piece of work, usually through a unique ID, and returns the earlier result instead of charging, sending or booking again.
Idempotency is the difference between a glitch and a refund queue. Without it, a slow connection can charge a card twice, two staff can accept the same job, and a webhook resent by a gateway can credit a wallet twice.
Designed in, it costs little: a unique key per action, a unique index in the database and an atomic update that claims the work. Retrofitting it after duplicates have reached the ledger is far harder.
Idempotency at a glance
- Protects
- Payments, refunds, sends and bookings
- Built from
- A unique ID per action and an atomic claim
- Test with
- The same request sent twice at once
Where has idempotency come up in our builds?
A refund already recorded under its Stripe refund ID is never booked twice, and having a single webhook consumer means no Stripe event is processed by both backends.
Accepting a rescue case is compare-and-set, so when two responders tap Accept together, one wins and the other gets a 409.
The receiver kit's publisher runs every minute in every instance of the customer's app, and publishing is a conditional update on the post's status, so two instances that tick together publish a post once. That case has its own test among the kit's 29.
Common questions about idempotency
How do I stop customers being charged twice?
Give each payment attempt a unique key, record provider events under their own IDs before acting on them, and make the step that grants access or credits a wallet check whether it has already run.
What should happen when two people accept the same job at the same moment?
One should win and the other should get a clear 'already taken' reply. That needs an atomic compare-and-set on the job's status, not a check followed by a separate write.
Related terms
Sources
Planning a product and not sure where idempotency fits? Ask us, or browse all 116 terms in the glossary.