Idempotency - Spree Commerce documentation

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:

First request — process normally and cache the response for 24 hours
Duplicate request (same key, same parameters) — return the cached response without re-executing the operation
Key reuse with different parameters — return a 422 error to prevent misuse

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.

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

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 per API key — different API keys can use the same idempotency key 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:

{
  "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:

{
  "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:

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

​How It Works

​Supported Endpoints

​Key Requirements

​Response Headers

​Error Handling

​Key Reuse with Different Parameters

​Key Too Long

​Server Errors

​SDK Usage

​Best Practices

​Relationship with Optimistic Locking