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 duplicate requests.
Requests that process credit card payments, create billing attempts for subscriptions, or capture revenue details accept idempotency keys. Generally, requests that update or delete objects (for example, inventoryShipmentUpdateItemQuantities) are idempotent by definition, and don't require you to send an idempotency key as part of the request.
However, some update / delete mutations, such as inventoryTransferSetItems, might not be naturally idempotent, because they might perform non-idempotent operations on the side, in addition to the main operation. These mutations require an idempotency key.
You can use any unique identifier for your idempotency key, but we recommend using a randomly generated universally unique identifier (UUID) to avoid collisions.
You can use any unique identifier for your idempotency key, but we recommend using a randomly generated universally unique identifier (UUID) to avoid collisions.
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:
POST https://{shop}.myshopify.com/api/{api_version}/graphql.json
Anchor to Idempotency directivesIdempotency directives
While some mutations, such as the one shown in the previous example, accept idempotency keys as arguments, others use directives. Directives are just a different GraphQL syntax for passing in idempotency keys to the mutation.
Mutations that accept an @idempotent directive specify that they do in their descriptions. Learn more about implementing idempotency for mutations accepting an @idempotent directive.
Below is an example of a mutation using the directive syntax: