Skip to main content

Idempotency

Use the Idempotency-Key header on all order management requests that modify an order. This ensures operations are performed exactly once, even if you retry the request due to network errors or timeouts.

Supported operations​

The Idempotency-Key header is supported on all order management requests that modify an order:

  • Capture (full and partial)
  • Refund (full and partial)
  • Edit order
  • Edit customer and edit payment method
  • Extend order expiry
  • Set reference

Usage​

Include the header with a unique value (we recommend UUID v4):

curl -X POST \
  -H 'authorization: Bearer v4.public.eyJpc3MiOiJs...' \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: da7ca8f9-915b-472b-b5f0-81945bff9e4a' \
  https://api.sandbox.ledyer.com/v1/orders/:orderId/capture

Best practices​

Generate a unique key per operation

Each operation needs its own key. Don't reuse keys across different operations or orders.

Retry with the same key

When retrying failed requests, use the same idempotency key. If the original request succeeded, you'll receive the original response.

Store keys for debugging

Keep a record of which idempotency key was used for each operation to help with debugging and auditing.

When not needed​

Read-only operations (GET order, GET orders, GET payment status) don't require the Idempotency-Key header as these operations are naturally idempotent.