Idempotent requests

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.

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:

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

• AppRevenueAttributionRecord
• AppRevenueAttributionRecordInput
• SubscriptionBillingAttempt
• SubscriptionBillingAttemptInput
• subscriptionBillingAttemptCreate

GraphQL Storefront API

• Payment
• CreditCardPaymentInputV2
• TokenizedPaymentInputV3
• checkoutCompleteWithTokenizedPaymentV3

REST Admin API

• Payment