Status 

Idempotency-key support is partial today. Selected internal retry mutations — for example, the order-billing retry and refund-billing retry flows — already accept an idempotency key and use it to deduplicate downstream payment-processor calls. There is not yet a standardized idempotencyKey argument across all customer-facing create mutations on the Zonos Graph; that is on the roadmap. Until it ships, use the patterns below to keep mutations safe to retry.

Safe-by-default mutations 

Some mutations are naturally idempotent because they upsert by a stable identifier you provide. When you call these with the same input, the result is the same — there is no risk of creating duplicates.

• Mutations that take a unique merchant-supplied identifier (for example, an order externalId) will return the existing record on a repeat call rather than creating a new one.
• Read-only operations (queries) are always safe to retry.

When you can attach your own stable identifier to the resource you are creating, prefer that path.

Patterns for mutations that are not naturally idempotent 

For mutations that create resources without a merchant-supplied key, treat them as at-most-once from your side:

1. Persist the request before sending. Write a row to your own database (status pending) before the network call.
2. Send the mutation. On success, record the returned resource id against your pending row (status committed).
3. On network error, do not blindly retry. Query the Zonos Graph to determine whether the resource was created (for example, by listing resources created in the last few minutes for your account, or by querying for a related resource you can correlate). Only retry if you can confirm the resource is not present.
4. Use a unique constraint in your own database on whatever business key represents the request, so a duplicate retry from your own application cannot double-submit.

Webhook delivery is at-least-once 

When you consume Zonos webhooks, design handlers to be idempotent — the same event may be delivered more than once. Deduplicate by the event id. See Webhooks for the event id field.

Where the platform is heading 

The underlying platform already runs idempotency-key flows in production for billing retries: the key scopes a retry attempt and prevents duplicate payment-processor calls. We are working to expose the same pattern as an optional idempotencyKey argument on customer-facing create mutations. When supplied, the Graph will return the original response for any subsequent call with the same key within a retention window. This page will be updated when the surface is generally available.

If standardized idempotency keys on customer-facing mutations are blocking your integration, contact support.