Order creation and session creation require Idempotency-Key: 16–128 letters, numbers, underscores or hyphens. Generate one per intended operation and reuse it with the same request after a timeout or temporary failure.
Keys are scoped to the merchant, mode and operation. Replay records last seven days. Reusing a key after that window can start another operation, but order references remain unique for the merchant and mode.
A matching order reference returns the existing order even when you supply a new idempotency key. Changed contents under the same reference or active key return 409 idempotency_conflict. Keep optional fields and item order consistent on retries.
Retries do not extend order expiry or revive a revoked, expired or deleted checkout session. To replace a link, create a new session with a new idempotency key while the order is still open.
