IoneShop Developers

Idempotency

Unsafe writes (POST that creates side effects, payment captures, sync upserts) must be idempotent under retries.

Header

Idempotency-Key: <client-generated-unique-string>
  • Max length: 255
  • Recommended: UUIDv4 or deterministic key from business id (erp_order_99881)
  • Scoped per API credential
  • Retention: 24 hours (Enterprise may extend)

Behaviour

  1. First request with key → processed; response stored
  2. Replay with same key + same request body hash → original response (possibly Idempotent-Replayed: true)
  3. Same key + different body → 409 IDEMPOTENCY_KEY_REUSED

Required for

  • Creating orders / payment intents
  • Refunds / captures
  • Webhook endpoint creation
  • Batch upserts
  • Inventory absolute sets from ERP (use business-natural keys)

Example

curl -sS -X POST "https://api.ioneshop.cloud/v1/orders/ord_01J.../refunds" \
  -H "Authorization: Bearer $IONESHOP_API_KEY" \
  -H "Idempotency-Key: refund_ord_01J_full_1" \
  -H "Content-Type: application/json" \
  -d '{"amount":{"amount":4999,"currency":"EUR"},"reason":"customer_request"}'

Network timeout? Retry with the same Idempotency-Key — do not mint a new key.