Public beta

Idempotency keys

Network errors happen. Idempotency keys let you safely retry create requests without risking duplicate deliveries.

Coming soon — required before Shopify launch

ETA: Q2 2026

The Idempotency-Key header is documented now so your client code can be built against the final shape. Until middleware ships, the header is silently ignored — duplicate POSTs will still create duplicate deliveries. Build your retry logic to support it; we will turn it on server-side before Shopify ships.

Sending an idempotency key

Pass an Idempotency-Key header on any POST request that creates a resource. Reuse the same key when retrying.

curl -X POST https:"color:#6a9955">//api.zippex.com/v1/deliveries \
  -H "Authorization: Bearer zx_test_abc123def456" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{ "quote_id": "qt_r4s5t6u7", "pickup_name": "...", "..." }'

How keys are scoped

Keys are scoped to your API key + endpoint + method.
Keys persist for 24 hours after the first successful request.
Replays return the original response body and original status code.
Generate UUID v4 keys client-side. Do not reuse keys across logically different requests.

Body must match on replay

Sending the same idempotency key with a different request body returns 409 Conflict. Generate a new key when the request changes.