UCP Checkout – Definition, Statuses and the continue_url Handoff
UCP checkout is the part of the Universal Commerce Protocol where an AI agent builds an order with a store: it creates a checkout session, adds items, a buyer and an address, and reads live totals. The capability is called dev.ucp.shopping.checkout.
The agent fills the checkout over an API, and when something needs the buyer – payment, a review, a choice – the store gives a link back to its own checkout.
The six statuses
Every checkout session has a status. It tells the agent what to do next:
| Status | Meaning | What the agent does |
|---|---|---|
incomplete | Information is missing or there is a problem the agent can fix | Fix it with Update Checkout |
requires_escalation | The rest needs the buyer, or information the API cannot collect | Fix what it can, then send the buyer to continue_url |
ready_for_complete | Everything is there | Call Complete Checkout |
complete_in_progress | Complete was accepted; the store is processing | Wait and read again |
completed | The order is placed; an order is in the answer | Show the order to the buyer |
canceled | Expired or cancelled | Start a new session if needed |
requires_escalation and continue_url
requires_escalation is not an error. It means: “I have everything the API can give me. The buyer must finish this on the store.” The spec says the store must send a continue_url with this status: an absolute HTTPS link that opens the same checkout in the buyer’s browser.
This is the safe default for most stores today. The agent never handles payment. The buyer pays on the checkout they already trust, with the payment methods, fraud checks and terms the store already has.
The operations
| Operation | Call |
|---|---|
| Create Checkout | POST /checkout-sessions |
| Get Checkout | GET /checkout-sessions/{id} |
| Update Checkout | PUT /checkout-sessions/{id} — a full replacement, not a patch |
| Complete Checkout | POST /checkout-sessions/{id}/complete |
| Cancel Checkout | POST /checkout-sessions/{id}/cancel |
The same operations exist as MCP tools in the MCP binding. Two extensions often come with checkout: fulfillment (shipping address and the store’s live shipping options) and discount (coupon codes). A separate order capability lets the agent read the order after it is placed.
What a store must get right
- Live totals. Shipping and tax must be real, from the store’s own rules.
- Idempotency. An agent retries on timeouts. The same
Idempotency-Keywith the same body must return the same answer, not a second session. - Clear messages. Each problem needs a
paththat says which field is wrong, so the agent can fix it in one call. - Advertise only what works. Declare checkout in
/.well-known/ucponly when an endpoint really serves it.
A Magento example
The UCP Checkout module creates a guest quote for each session, returns your live Magento shipping rates for the address the agent sends, and applies coupon codes. Complete Checkout always returns requires_escalation with a continue_url. The link opens the cart in the buyer’s browser with the address and shipping method set, and the buyer pays on the normal Magento checkout. When the order is placed, the session moves to completed, and the platform that created it can read the order and receive signed webhooks.
Questions
- Does UCP checkout mean the AI agent pays?
- Not necessarily. Payment through the agent needs a payment handler and, for example, AP2 mandates. Many stores return requires_escalation instead, so the buyer pays on the store’s own checkout.
- Is requires_escalation a failure?
- No. It means the API part is done and the buyer must finish on the store. The store must send a continue_url with it.
- Is UCP checkout the same as ACP checkout?
- No. They are different protocols. ACP comes from OpenAI and Stripe. UCP is advertised in /.well-known/ucp and is the route to Google AI Mode and Gemini.
- Can an agent use MCP instead of REST?
- Yes. UCP defines an MCP binding with the same operations as tools.
Related
- UCP for Magento 2 – complete guide
- UCP – definition
- /.well-known/ucp – definition
- Agentic checkout – definition
- AP2 – definition
- UCP Checkout module