UCP Idempotency Keys: Why Every Agent Transaction Needs One

One of the most underappreciated features in any commerce protocol is idempotency. In human-driven commerce, duplicate purchases are rare — a human notices when they have submitted the same order twice. In agentic commerce, where the agent may retry a failed request, receive a timeout, or encounter an ambiguous confirmation response, duplicate transactions are a real operational risk. UCP’s idempotency key implementation is designed to eliminate this risk.

What Is Idempotency in Commerce

An operation is idempotent if performing it multiple times produces the same result as performing it once. In commerce, an idempotent checkout means that submitting the same order twice — with the same idempotency key — results in exactly one charge and one order, not two. The second submission returns the result of the first rather than creating a duplicate.

Why Agents Need Idempotency More Than Humans

Agents operate in uncertain network conditions. A POST request to initiate checkout may succeed on the merchant side but return a network error to the agent. The agent, having received no confirmation, may retry. Without idempotency keys, this produces a duplicate order and a double charge. With idempotency keys, the retry returns the original confirmation. The agent can proceed without the human behind it being charged twice for one purchase.

How UCP Implements Idempotency Keys

Every UCP checkout initiation includes a client-generated idempotency key — a unique string associated with this specific transaction attempt. The merchant’s UCP implementation stores this key for a defined window (typically 24 hours). If the same key is received again within that window, the stored result is returned. If a different key is received for the same cart, it is treated as a new transaction.

Key Generation Best Practices

Idempotency keys should be long enough to be globally unique (UUID v4 is the standard), generated client-side by the agent at the start of each checkout attempt, and included in every retry for the same transaction. They should never be reused across different intended transactions. The key is the fingerprint of the specific purchase attempt, not the session or the cart.

Frequently Asked Questions

What happens if a merchant’s UCP implementation does not support idempotency keys?

This is a certification failure. UCP-certified merchants are required to implement idempotency key support for all checkout endpoints. Agents encountering non-idempotent checkouts should flag the merchant as non-compliant and escalate rather than retrying without protection.

Frequently Asked Questions