Implement idempotent agent checkout retries so that network failures and LLM re-invocations never produce duplicate orders or double-charges

In-depth guide

Steps

1. Generate a stable idempotency key at the start of each agent checkout task; the key must be derived from the task intent and its input parameters (e.g., a hash of agent session ID + cart contents + timestamp bucket), not from a random UUID that a re-invoked agent will not regenerate identically
2. Pass the idempotency key in every mutating API call — Stripe (Idempotency-Key header), PayPal (PayPal-Request-Id header), and other PSPs each have their own header name — consult each PSP's current documentation for the exact header and behavior guarantee
3. Store the idempotency key and its outcome (success, pending, or failure with error code) in a persistent key-value store that the agent runtime can read on retry; if the stored outcome is success, return the cached result immediately without re-executing the API call
4. Set an expiry on idempotency keys consistent with your task retry window (e.g., 24 hours for a same-day purchase task); PSPs impose their own server-side idempotency key TTLs — check current PSP documentation and ensure your client-side retention period is shorter to avoid serving a cached success after the PSP has expired its record
5. For ACP checkout sessions, use the checkout_session_id returned by the /checkout_sessions endpoint as a natural idempotency anchor for all subsequent session update and complete calls; do not create a new session on retry if the original session ID is still valid
6. Test with simulated network partitions: verify that a retry after a timeout-but-success scenario returns the cached successful outcome rather than creating a second order, and that a retry after a genuine failure correctly re-executes