Overview
Idempotency keys allow you to safely retry order creation requests without creating duplicate orders. This is especially useful when:
- Network timeouts occur
- Your server crashes before receiving a response
- You need to retry failed requests
- You want to prevent accidental duplicate orders
- You're implementing webhook retry logic
Implementation
Include the Idempotency-Key header in your POST request:
Format: Any unique string (UUID v4 recommended)
Optional header (if omitted, orders are created normally)
Idempotency-Key: <your-unique-key>
If you send different order data with the same key, the original order is returned (first request's data is preserved).
Response Behavior
| Scenario | Status Code | Response Header |
|---|---|---|
| New order created | 201 Created | None |
| Existing order returned | 200 OK | X-Idempotent-Replay: true |
Response Headers
When an existing order is returned (replay scenario), the response includes:
X-Idempotent-Replay: true
This header indicates that the response is a replay of a previous request, not a newly created order.
Note
Idempotency keys are currently only supported for the POST /v2/orders (Create order) endpoint. Other endpoints do not support idempotency at this time.