Stripe API Idempotency: A Practical Example

Network requests fail. Retrying a payment creation request without protection risks charging a customer twice — idempotency keys solve this at the API level.

await stripe.paymentIntents.create(
  { amount: 2000, currency: "usd", customer: customerId },
  { idempotencyKey: `order-${orderId}` }
);

If the same idempotency key is sent twice, Stripe returns the original response instead of creating a second charge — even if your first request technically succeeded but your client never received the response.

Choosing a Good Key

Tie the key to something meaningful and unique in your system — an order ID, not a random UUID generated fresh on every retry, which defeats the purpose entirely.