Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: "Idempotency"
sidebarTitle: "Idempotency"
description: "Use Idempotency-Key headers on Spree Store API mutations to safely retry carts, checkouts, and payments without creating duplicate side effects."
---
The Store API supports idempotency keys on mutating endpoints. This lets you safely retry requests without risking duplicate side effects — for example, adding an item to cart twice or creating duplicate payments due to network timeouts.
## How It Works
Include an `Idempotency-Key` header with a unique value (e.g., a UUID) on any supported request. The API will:
1. **First request** — process normally and cache the response for 24 hours
2. **Duplicate request** (same key, same parameters) — return the cached response without re-executing the operation
3. **Key reuse with different parameters** — return a `422` error to prevent misuse
```bash
curl -X POST https://api.mystore.com/api/v3/store/carts/cart_xxx/items \
-H "X-Spree-API-Key: pk_xxx" \
-H "X-Spree-Token: abc123" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{"variant_id": "variant_xxx", "quantity": 1}'
```
If the client retries this exact request with the same idempotency key, the API returns the original response with an `Idempotent-Replayed: true` header — without adding the item again.
## Who A Cached Response Belongs To
A cached response is only ever returned to the caller that produced it, so the request has to say who that caller is. One of these identifies them:
- the **customer's access token** (`Authorization: Bearer ...`), for a signed-in shopper
- the **cart token** (`X-Spree-Token`), for a guest working on a cart they already hold
- a **secret key** (`sk_...`), for a server-to-server caller on the Admin API
Retry with the same credentials you sent the first time. A replay answers from the cache without running the request again, so it never re-checks your access — a retry that drops or swaps a credential is treated as a different caller and runs for real.
Your publishable key (`pk_...`) does not count. Every visitor to your storefront sends the same one, so a key value that two shoppers happen to share — `checkout-1`, an order number, a timestamp — would hand one shopper the other's response, cart token included.
A request that carries none of the credentials above still runs exactly as it always has — it is simply never cached, so the `Idempotency-Key` header has no effect on it. Guests are not second-class here: a guest holds a cart token from the moment their cart exists, which covers the whole of checkout, including the steps where a duplicate costs money.
## Supported Endpoints
| Endpoint | Actions |
|----------|---------|
| `POST /carts` | Cart creation |
| `PATCH /carts/:id` | Cart updates |
| `POST /carts/:id/complete` | Order completion |
| `POST /carts/:id/items` | Adding items to cart |
| `POST /carts/:id/payment_sessions` | Payment session creation |
| `PATCH /carts/:id/payment_sessions/:id/complete` | Payment completion |
| `POST /carts/:id/coupon_codes` | Applying coupon codes |
| `POST /carts/:id/store_credits` | Applying store credits |
Every one of these is replayable for a guest as well as for a signed-in shopper, because every one of them is reached with the cart's token. The exception is creating the cart itself: there is no cart yet, so a guest has no token to present and the key is ignored — a retry may leave behind a second, empty cart. Sign the shopper in, or accept the spare cart.
Idempotency keys are ignored on `GET`, `DELETE`, and other non-supported actions.
## Key Requirements
- Must be a string of **255 characters or less**
- Should be unique per distinct operation (UUIDs are recommended)
- Keys are scoped to the caller and the store, so two callers can use the same key value without conflict
- Cached responses expire after **24 hours**
## Response Headers
When a cached response is replayed, the API sets:
```
Idempotent-Replayed: true
```
You can use this header to detect replayed responses in your application or logging.
## Error Handling
### Key Reuse with Different Parameters
If you send a request with an idempotency key that was previously used with different request parameters (different body, different path), the API returns a `422` error:
```json
{
"error": {
"code": "idempotency_key_reused",
"message": "This Idempotency-Key has already been used with different request parameters."
}
}
```
### Key Too Long
Keys longer than 255 characters return a `400` error:
```json
{
"error": {
"code": "invalid_request",
"message": "Idempotency-Key must be 255 characters or less."
}
}
```
### Server Errors
`5xx` responses are **not cached**. If the server fails to process your request, you can safely retry with the same idempotency key and the request will be re-executed.
## SDK Usage
The Spree SDK supports idempotency keys via the `idempotencyKey` option:
```typescript
import { createClient } from '@spree/sdk'
const client = createClient({
baseUrl: 'http://localhost:3000',
publishableKey: 'pk_xxx',
})
// Add item to cart with idempotency key
await client.carts.items.create(cartId, {
variant_id: 'variant_xxx',
quantity: 1,
}, {
idempotencyKey: '550e8400-e29b-41d4-a716-446655440000',
})
```
## Best Practices
- **Generate a new key for each distinct operation.** Use a UUID (v4) or another random identifier. Never reuse keys across different operations.
- **Store the key before sending the request.** If the request fails due to a network error, retry with the same key to ensure the operation is only performed once.
- **Don't use idempotency keys for GET requests.** GET requests are naturally idempotent and the API ignores the header on read-only endpoints.
- **Let keys expire naturally.** Cached responses expire after 24 hours. Don't rely on idempotency keys for longer-term deduplication.
## Relationship with Optimistic Locking
The Store API also uses [optimistic locking](/api-reference/store-api/introduction) via the `state_lock_version` field on orders. These mechanisms complement each other:
| Mechanism | Prevents | Scope |
|-----------|----------|-------|
| **Idempotency keys** | Duplicate operations from retries | Per-request deduplication |
| **Optimistic locking** (`state_lock_version`) | Concurrent modifications | Conflict detection between clients |
Use both together for robust checkout flows: idempotency keys protect against network retries, while `state_lock_version` detects when another client has modified the order.