Insights · Nov 12, 2026 · 4 min read · FAQ

Idempotency keys for checkout and order APIs: stop double charges

A double tap or a dropped mobile connection can send the same checkout request twice. An idempotency key lets your API run it once and replay the result.

IDEMPOTENCY KEYSNo double charges on retry SELLWRIGHT

A customer taps Pay on a slow mobile connection, sees the spinner stall and taps again. Or your app times out waiting for the server and retries on its own. Either way, your order API receives the same request twice, with nothing to tell a retry from a second purchase. The result is two orders, sometimes two charges, then a refund and an apology. Idempotency keys fix this, and Stripe uses them on its own API.

What is an idempotency key?

It is a unique value the client creates for one operation and sends with every attempt at it, so the server can recognise a retry. It travels in the Idempotency-Key header, the name Stripe uses and an IETF draft sets out to standardise.

POST /api/orders HTTP/1.1
Content-Type: application/json
Idempotency-Key: "8e03978e-40d5-43e8-bc93-6894a57f9324"

{"cartId": "cart_7f2a", "shipping": "standard"}

The key belongs to the action, not the attempt: create it once when the customer starts checkout and send the same value on every retry. In the browser, crypto.randomUUID() returns a random version 4 UUID on HTTPS pages. Stripe suggests V4 UUIDs or another random string with enough entropy, and accepts keys up to 255 characters. The draft quotes the value; Stripe's examples don't, so accept both.

Which requests need one?

Any POST that creates something or moves money needs a key; GET, PUT and DELETE are already idempotent by HTTP's own definition. RFC 9110 calls a method idempotent when several identical requests have the same intended effect on the server as one, and lists PUT, DELETE and the safe methods such as GET. It also says clients should not automatically retry non-idempotent requests without some way to know a repeat is harmless. The key is that way.

  • Key it: creating an order, charging or refunding a payment, booking a slot, sending an invoice or a message.
  • No key needed: reads, a PUT that replaces a record in full, a DELETE of a known record. Stripe says keys on its v1 GET and DELETE requests have no effect.
  • Check PATCH: RFC 5789 says it is neither safe nor idempotent. A change that adds to a value, such as one more on a quantity, needs a key or a rewrite as a set-to change.

What should the server do with the key?

Store the first result under the key and return it to every repeat. In practice:

  1. Validate the key's format and scope it to the account, so one customer's key never matches another's. The IETF draft recommends a composite lookup key for this.
  2. Insert a record with the key, a hash of the request body and the status in progress, under a unique constraint, so only one of two simultaneous requests can win.
  3. Run the operation. When it calls a payment provider, send that provider a key too, derived from your order.
  4. Save the status code and response body against the key and mark it complete.
  5. On a repeat, check the body hash and return the saved response without running anything.

Decide which outcomes you store. Stripe's v1 API saves the response once the endpoint starts running, 500 errors included, but not requests that failed validation or clashed with a concurrent one; those can be retried.

What if the same key comes with a different body?

Reject it with an error: never replay the old result and never run the new request. Stripe compares the parameters with the original request and errors if they differ. The IETF draft suggests 422 Unprocessable Content with a link to your documentation. Stripe's advice: first establish that the original did not succeed and is not still running, then use a new key.

What if a duplicate arrives while the first is still running?

Return a conflict and start nothing. The draft recommends 409 Conflict when a request is retried while the original is still being processed. Stripe tells its own clients to wait and retry a 409 with the same key and parameters, since a new key could start a second operation. Do the same, with a short backoff.

This is where simple implementations fail: a double tap sends two requests milliseconds apart, neither finds a finished result, and both charge. The unique insert in step 2 prevents it.

How long should you keep keys?

Long enough to cover every retry your clients make; then expire them and publish the window. Stripe's v1 API keeps keys for at least 24 hours and can remove them after that, after which a reused key can run as a new request; its v2 API treats requests within 30 days of each other as replays. The IETF draft says an API should define its expiry policy and publish it. Past the window, clients should stop retrying and check what happened: Stripe says to retrieve the object and reconcile first.

Test it the way customers break it: double-tap Pay on a throttled connection, then fire the same request twice at once from a script. You want one order, one charge, one email.

Where to start

List every endpoint that creates an order, takes a payment or messages a customer, and check each one: the client reuses its key on retries, the server replays the first result, an in-progress duplicate gets a 409, and a changed body gets an error. Our web app development service builds checkout and order APIs this way in Next.js. For events a provider sends to you, see reliable webhooks.

FAQ

Frequently asked questions

Isn't disabling the Pay button after one click enough?

No, though it is still worth doing. A disabled button stops the obvious double click, but not an automatic retry after a timeout, a request resent when a mobile connection drops, or a customer who refreshes and submits again. Only the server can tell that two requests are the same action, and the key is how it knows.

Does Stripe already protect us from double charges?

Only for requests your server sends to Stripe with a key. Stripe's SDKs can generate keys and retry automatically, but if your own API creates two orders from one tap, it sends two separate charge requests, and nothing tells Stripe they belong to one purchase. You need keys at both layers: from your client to your API, and from your server to Stripe.

Can we use the cart ID as the idempotency key?

Yes. Stripe lists deriving the key from an object such as a shopping cart ID as a common strategy, because it guards against double submissions. If the customer can change the cart after a failed attempt, add a version so new contents get a new key. Avoid personal data such as email addresses in keys; Stripe advises against it.

Is the Idempotency-Key header an official HTTP standard?

Not yet. It is defined in an IETF Internet-Draft from the HTTPAPI working group, The Idempotency-Key HTTP Header Field, whose latest version is 08, dated 22 October 2026. It has not been published as an RFC, so details may still change before it is. Stripe already uses the same header name.

How can a client tell a replayed response from a fresh one?

Mark replays with a response header. Stripe sends Idempotent-Replayed: true when it returns a saved response, and the convention is cheap to copy. Beyond that, the replay should carry the original status code and body, so the client handles it like the first answer and the customer sees one confirmation, not an error.

Next step

Ready for a website that sells?

Book a short call. We will look at your current site, agree what matters most and send a written scope with a fixed quote.

Book a callOr write to hello@sellwrightstudio.com