UCP Checkout lifecycle: the 6 states to implement

Published 23 August 2026 . Part of the UCP implementation guide.

A UCP checkout is not a simple form. It is a state machine that tells the platform and merchant whether the transaction can progress, needs buyer action, or must be abandoned.

Key takeaways

• The specification defines 6 checkout states.
• messages explains the correction or authorization each state requires.
• Only ready_for_complete allows programmatic completion.

What are the six Checkout states?

The Checkout specification defines incomplete, requires_escalation, ready_for_complete, complete_in_progress, completed, and canceled.

State	Meaning	Platform action
incomplete	information is missing or correctable	inspect messages, update
requires_escalation	buyer intervention is required	open continue_url
ready_for_complete	all required data is present	call Complete Checkout
complete_in_progress	merchant is processing	wait or read the state
completed	order has been placed	use the Order resource
canceled	session is invalid or expired	create a new session

The top-level ucp.status does not replace this business state. It discriminates the response shape: success carries the expected resource, while error carries error information. Implementations must inspect both levels.

How should incomplete be handled?

incomplete means an API update can still resolve the problem. The platform reads messages, corrects the referenced field, and sends Update Checkout. Field paths use JSONPath, which can point precisely to an address, line item, or fulfillment option.

The recoverable severity confirms that the agent can fix the issue. An unavailable quantity may lead to a line update. A platform should not open a human interface while a deterministic correction remains possible.

When must the buyer take over?

requires_buyer_input and requires_buyer_review both contribute to requires_escalation. The first asks for information unavailable through the API. The second requires review or authorization, potentially because of policy or regulation.

In either case, the platform opens continue_url. That URL should recover server-side state. It should not encode the entire checkout or expose sensitive data in its path.

Why is completion a separate phase?

ready_for_complete confirms that the required data is present. The platform may call Complete Checkout. The merchant moves to complete_in_progress during processing and then completed once the order exists.

This separation prevents a network response from being mistaken for commercial success. A timeout after Complete Checkout is not permission to create another transaction. The client should read the state and reuse the same idempotency key.

Not all warnings are optional

A warning may be a normal notice or a disclosure. A notice must be displayed but may be dismissed. A disclosure must appear near the referenced component and cannot be hidden or automatically dismissed.

The agent interface must preserve that distinction. Rendering all warnings as secondary text could make the payload valid while violating the merchant’s presentation contract.

Minimum pre-production tests

• represent every state in integration tests;
• route a recoverable error through Update Checkout;
• route requires_* severity through buyer handoff;
• never call Complete Checkout from incomplete;
• handle a completion timeout by reading state, not creating a new order;
• replace a canceled session instead of reviving it.

The earlier transition is documented in UCP Cart or Checkout. The full merchant architecture is covered by the UCP implementation guide.

Sources

• UCP, Checkout Capability
• UCP, REST binding for Checkout
• UCP, Cart Capability

---

Back to the UCP implementation guide · All notes · Lire en français