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

ExpandOn this page

* [What is an idempotency key?](https://shopify.dev/docs/api/admin-rest/usage/idempotent-requests.md#what-is-an-idempotency-key)
* [How idempotent requests work](https://shopify.dev/docs/api/admin-rest/usage/idempotent-requests.md#how-idempotent-requests-work)
* [Requests that accept idempotency keys](https://shopify.dev/docs/api/admin-rest/usage/idempotent-requests.md#requests-that-accept-idempotency-keys)

# Idempotent requests in the REST Admin API

Legacy

The REST Admin API is a legacy API as of October 1, 2024. All apps and integrations should be built with the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql). For details and migration steps, visit our [migration guide](https://shopify.dev/docs/apps/build/graphql/migrate).

The REST Admin API supports idempotency, which allows you to safely retry API requests that might have failed due to connection issues, without causing duplication or conflicts.

***

## What is an idempotency key?

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

***

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

For example, you might be using the REST Admin API's [`Payment`](https://shopify.dev/docs/api/admin-rest/latest/resources/payment) resource 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:

```text
POST /admin/checkouts/#{token}/payments.json HTTP/1.1
Host: shop-name.myshopify.com
Content-Type: application/json
X-Shopify-Access-Token: #{shopify_access_token}


{
"payment": {
  "request_details": {
    "ip_address": "123.1.1.1",
    "accept_language": "en-US,en;q=0.8,fr;q=0.6",
    "user_agent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/54.0.2840.98 Safari\/537.36"
  },
  "amount": "1675.99",
  "session_id": #{id},
  "unique_token": "client-side-idempotency-key"
}
}
```

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.

***

## Requests that accept idempotency keys

POST requests that process credit card [payments](https://shopify.dev/docs/api/admin-rest/latest/resources/payment), 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.

***

* [What is an idempotency key?](https://shopify.dev/docs/api/admin-rest/usage/idempotent-requests.md#what-is-an-idempotency-key)
* [How idempotent requests work](https://shopify.dev/docs/api/admin-rest/usage/idempotent-requests.md#how-idempotent-requests-work)
* [Requests that accept idempotency keys](https://shopify.dev/docs/api/admin-rest/usage/idempotent-requests.md#requests-that-accept-idempotency-keys)