Idempotency

An idempotency key identifies one logical write operation. Your backend generates and stores the key before it sends the first request.

Generate and store a key

Generate a UUID for each new operation. The key is an identifier, not a credential.

const idempotencyKey = crypto.randomUUID();

Store the key with your order, checkout attempt, or refund before sending the request. A retry must read the stored value instead of generating another key.

Send the key

Operations that declare Idempotency-Key in the API reference require this header:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Use one key according to these rules:

• First attempt: send the key stored for that operation
• Same operation retry: reuse the same key and the same request payload
• New operation: generate and store a new key
• Changed payload or endpoint: use a new key because it represents a new operation

The same key and request return the original operation result. Reusing a key with a different request returns 409 idempotency_conflict.