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.

Anchor to Idempotency keysIdempotency keys

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

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

Anchor to How idempotent requests workHow 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 are executed only once, no matter how many times the request is retried.

For example, the subscriptionBillingAttemptCreate mutation supports idempotency. By including an idempotency key in your request, you ensure that repeated requests with the same parameters are executed only once, regardless of how many times the request is retried:

Anchor to Idempotency directivesIdempotency directives

While some mutations accept idempotency keys as arguments to the mutation, such as the one above, others use directives (the difference is ultimately just syntax).

Mutations that accept an idempotency directive specify that they do in their descriptions.

Below is an example of a mutation using the directive syntax: