Skip to main content

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.


An idempotency key (idempotencyKey) 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 will be 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 will be executed only once, regardless of how many times the request is retried:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

mutation {
subscriptionBillingAttemptCreate(input: {
subscriptionContractId: "gid://shopify/SubscriptionContract/123456789",
idempotencyKey: "unique-idempotency-key"
}) {
subscriptionBillingAttempt {
id
status
}
userErrors {
field
message
}
}
}
Tip

You can use any unique identifier for your idempotency key, but we recommend using a randomly generated universally unique identifier (UUID) to avoid collisions.


Was this page helpful?