Prevent Duplicates

Idempotency keys ensure that retrying a request won’t create duplicate orders or charges.

How It Works

Send a unique key in the Idempotency-Key header with your POST request. The same key will always return the same result.

Safe Retries

If a network error or timeout occurs, simply retry with the same key to get the original response.

Key Expiration

Idempotency keys expire after 24 hours.

​
What is an Idempotency Key?

Idempotency keys are unique strings you provide in the Idempotency-Key header of POST requests. They help prevent duplicate processing if a request is retried due to network issues or client timeouts. It is recommended to use V4 UUIDs (or similar) to avoid collisions. Although, it’s reasonable to construct your own key using a combination of known values, such as userId/timestamp.

Only POST requests accept idempotency keys. Other request types will ignore them.

We store and validate idempotency keys for 24 hours. This time frame should be enough to retry any failed processes.

​
How to Use Idempotency Keys

1

Generate a Unique Key

Create a unique string (such as a V4 UUID) for each logical request you want to be idempotent.

2

Add the Header

Include the key in your request headers: 

Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000

3

Send Your Request

Make your POST request as usual. If you retry with the same key, you’ll get the same response (not a duplicate order).

​
Example

POST /v1/orders
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000
Content-Type: application/json

{
  "items": [ ... ],
  "toAddress": { ... }
}

Troubleshooting & Tips

  • Always use a new idempotency key for each unique order or operation.
  • Reusing a key with a different payload will result in an error.
  • Keys are case-sensitive and should be unique per integration.
  • Idempotency keys expire after a period (typically 24 hours).
  • If you get an error about a reused key, generate a new one for your next request.