Skip to content

Idempotency

Networks retry. A well-behaved integration can send the same request twice — on a timeout, a connection reset, or an at-least-once queue — and litecommerce should not double-apply the effect.

Some surfaces already encode this. Public signup, for example, is a no-op on a repeat submission for the same email rather than creating a duplicate pending request.

Idempotency keys on commerce writes

The shared-commerce mutating endpoints accept an opt-in idempotency key so a safe retry replays the original outcome instead of creating a duplicate document, payment, or refund.

  • Header: x-idempotency-key (optional). Omit it and the operation runs directly; supply it — a UUID per logical request — to make retries safe.
  • Where it's honored: commerce document creates (POST /merchant/commerce/{quotes,invoices,orders}) and the manual payment/refund writes (POST …/{invoices,orders}/{id}/{payments,refunds}).
  • Scope: the key identifies the request within (organization, namespace, key). A hash of the request payload is stored alongside it, so a retry that reuses the key with a different body is caught as a mismatch rather than silently replayed.

Replay semantics (the key identifies the request; the stored payload hash detects a mismatched replay):

  • First use → the operation runs and the result is recorded against the key.
  • Same key, same payload → the original result is replayed; no second write.
  • Same key, different payload → 409 (a key can't be reused for a different request).
  • Same key while the first request is still in flight → 409.

A general idempotency mechanism for other mutating endpoints beyond commerce is not yet wired — don't assume a global idempotency key is honored outside the commerce surfaces listed above until this page says so.

Related