POST /orders, POST /shipments, POST /tokens/{tokenId}/shipment and POST /keys/rotate require an Idempotency-Key header: 8-128 characters of A-Z a-z 0-9 _ -. Use your own order id, one per order.
Orders, shipments and key rotations are separate key spaces; the two shipment endpoints share one.
A missing or malformed key is 400 BAD_IDEMPOTENCY_KEY.
Retries
What counts as the same request
- An order is the same request when
pack_type,category,odds,quantity,recipientandrefund_addressmatch.partner_user_refis not compared.oddsis compared as resolved, so leaving it out and naming the pack’s default are the same request (and so arequantity: 1and noquantity). - A shipment is the same request when the token (or the set of
token_ids, in any order),holder,address,rateandcover_amountall match.
Getting a lost response back
- Replaying the POST is how you get a lost
paymentobject back:GET /orders/{id}andGET /shipments/{id}don’t include it. GET /orders/{id}also accepts theIdempotency-Keyyou sent, so after a lost response you can always find out how an order ended.- A key rotation replayed with the same key returns the same new key and its secret, within 10 minutes and before the new key is used. See Rotate a key.
Endpoints without a key
POST /tokens/{tokenId}/quote takes no key: every call issues a fresh quote, and an unused quote simply expires.
