Skip to main content

​
Idempotency

Use idempotency keys to safely retry POST requests without creating duplicate resources.

​
How It Works

Include an Idempotency-Key header with a unique value (UUID recommended) on POST requests. If the same key is sent again within 24 hours, the API returns the cached original response without re-executing the operation. 
curl -X POST https://api.headlesscommerce.io/v1/storefront/carts/{id}/checkout \
  -H "Authorization: Bearer pk_test_your_key" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "payment_provider": "stripe"}'

​
When to Use

Idempotency keys are recommended for operations that should not be duplicated:
EndpointWhy
POST /storefront/carts/{id}/checkoutPrevent duplicate orders
POST /admin/orders/{id}/paymentsPrevent duplicate charges
POST /admin/orders/{id}/refundsPrevent double refunds

​
Key Rules

  • Keys must be unique per request — use UUIDs
  • Keys are scoped to the store (API key)
  • Cached responses expire after 24 hours
  • Only successful responses (2xx) are cached
  • Different request bodies with the same key will return the original cached response
The Idempotency-Key header is optional. If omitted, the request is processed normally without idempotency protection.