Idempotency

Send the Idempotency-Key header on write requests to safely retry without creating duplicates.

Why idempotency?

Networks and clients can fail after the request is sent but before the response is received. If you retry, the server might process the same create or update twice. Idempotency keys ensure that the same key is processed at most once within a time window.

Supported endpoints

Idempotency is supported for: POST /orders, POST /orders/:id/fulfill, POST /orders/:id/cancel, POST /purchase_orders, and POST /stock_transfers.

How to use

Send a unique key in the Idempotency-Key header. Use a UUID, or a string that is unique per logical operation.

curl -X POST "https://your-org.inventra.io/api/v1/orders" \
  -H "Authorization: Bearer inv_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"items":[{"sku":"WIDGET-1","quantity":2}],"location_id":"..."}'

If you send the same key again within the TTL (24 hours), you receive the same response as the first request; the server does not create a second order.

Best practices

Generate a new key for each distinct operation (e.g. each order creation).
Store the key on your side if you need to retry; the server stores it for 24 hours.
Use a UUID v4 or a deterministic string derived from your business id.