---
title: Idempotent requests
description: >-
  Learn how to safely retry API requests that might have failed due to
  connection issues.
api_name: usage
source_url:
  html: 'https://shopify.dev/docs/api/usage/idempotent-requests'
  md: 'https://shopify.dev/docs/api/usage/idempotent-requests.md'
---

ExpandOn this page

* [Idempotency keys](https://shopify.dev/docs/api/usage/idempotent-requests.md#idempotency-keys)
* [How idempotent requests work](https://shopify.dev/docs/api/usage/idempotent-requests.md#how-idempotent-requests-work)
* [Idempotency directives](https://shopify.dev/docs/api/usage/idempotent-requests.md#idempotency-directives)

# 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 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.

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.

***

## 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 are executed only once, no matter how many times the request is retried.

For example, the [`subscriptionBillingAttemptCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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

```graphql
mutation {
  subscriptionBillingAttemptCreate(input: {
    subscriptionContractId: "gid://shopify/SubscriptionContract/123456789",
    idempotencyKey: "3f5b6ebf-143c-4da5-8d0f-fb8553bfd85d"
  }) {
    subscriptionBillingAttempt {
      id
      status
    }
    userErrors {
      field
      message
    }
  }
}
```

***

## Idempotency 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:

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

```graphql
mutation InventoryAdjustQuantities($input: InventoryAdjustQuantitiesInput!) {
  inventoryAdjustQuantities(input: $input) @idempotent(key: "3f5b6ebf-143c-4da5-8d0f-fb8553bfd85d") {
    inventoryAdjustmentGroup {
      id
      changes {
        delta
        name
        __typename
      }
      __typename
    }
    userErrors {
      field
      message
      __typename
    }
    __typename
  }
}
```

***

* [Idempotency keys](https://shopify.dev/docs/api/usage/idempotent-requests.md#idempotency-keys)
* [How idempotent requests work](https://shopify.dev/docs/api/usage/idempotent-requests.md#how-idempotent-requests-work)
* [Idempotency directives](https://shopify.dev/docs/api/usage/idempotent-requests.md#idempotency-directives)