Public beta

Idempotency keys

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

Coming soon

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 general availability.

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">//developer.zippex.app/api/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.