How it works
The word idempotent means that doing something twice has the same effect as doing it once. Setting a value is idempotent. Charging a card is not, unless the server is told that two requests are the same one.
The client generates a random key and sends it in a header. The server stores the key with the outcome of the first request. A retry with the same key returns that stored outcome and does not repeat the work.
Example: the double-submitted charge
A checkout script posts a payment request. The network drops before the response arrives, so the script cannot know if the charge happened.
Without a key, retrying risks charging the buyer twice. With one:
curl https://api.stripe.com/v1/customers \
-u sk_test_...: \
-H "Idempotency-Key: KG5LxwFBepaKHyUD" \
-d description="My First Test Customer"
Send that exact request twice and Stripe creates one customer. Stripe’s documentation states the details as of November 2026, for API v1:
- It saves the status code and body of the first request made with a key, once execution of the endpoint begins. Retries return the saved response, including
500errors. - Keys can be removed automatically once they are at least 24 hours old. After that, reusing a key creates a new request.
- The server compares the parameters of a retry with the original and returns an error if they differ, to catch accidental key reuse.
- Requests that fail validation, or that collide with a request still running, are not saved. You can retry those.
- All
POSTrequests accept a key.
Idempotency key versus a unique constraint
A database unique constraint stops a duplicate row, but it throws an error on the second attempt, and the caller still does not know what the first attempt did. An idempotency key returns the first attempt’s result, which is what a retrying client wants. Use the key for the network boundary and the constraint as a second guard.
How Clavem handles it
The License API has no idempotency-key header. Clavem gets the same safety another way.
- Stripe events. Every Stripe webhook event is processed once, keyed by its event id. A redelivered event, or one you replay, does not issue licenses again. See webhooks and Connecting Stripe.
- Activation. Send a
fingerprintwith activate. Activating again with a fingerprint already active on that license returns the same seat, with its name updated, rather than using a second seat. The client can safely retry after a timeout.
If you call Stripe yourself from your backend, for example to create a checkout, send your own Idempotency-Key per logical purchase attempt.
Questions
What should an idempotency key look like?
Stripe suggests a V4 UUID or another random string with enough entropy to avoid collisions, up to 255 characters, and says to avoid sensitive data such as email addresses.
Do GET requests need an idempotency key?
No. Stripe says GET and DELETE requests are idempotent by definition, so a key has no effect on them. Keys matter for requests that create or change something.