Idempotent requests

Shopify APIs support idempotency, which allows you to safely retry API requests that might have failed due to connection issues, without causing duplication or conflicts.

Idempotency keys

An idempotency key (idempotencyKey) or unique token (unique_token) is a unique string identifier generated by your app. Shopify uses this identifier to recognize subsequent retries of the same request.

How idempotent requests work

If an API request is disrupted in transit, then you might not receive a response. By including an idempotency key in your request, repeated requests with the same parameters will be executed only once, no matter how many times the request is retried.

For example, you might be using the REST Admin API to process a payment in Shopify. If you don't receive a response due to a network connection error, then you can retry the request with the same unique_token to guarantee that only one payment is processed:

Resources that accept idempotency keys

POST requests that process credit card payments, create billing attempts for subscriptions, or capture revenue details accept idempotency keys. GET and DELETE requests are idempotent by definition, and don't require you to send an idempotency key as part of the request.

Some examples of resources that accept an idempotency key (GraphQL) or a unique token (REST) include the following:

GraphQL Admin API

GraphQL Storefront API

REST Admin API