agentic.rayuduramisetti.com

Reading guide · spec 2026-08-25

How to read ucp.dev

About 45 pages, but most repeat one pattern. Learn the roles, read five pages, and the rest becomes lookup.

What UCP is made of

Architecture diagramComponents: Agent, Wallet, /.well-known/ucp, REST, MCP, A2A, Embedded, Catalog, Cart, Checkout, Order, Payment handlers, PSPStore · Merchant of RecordTransportsCapabilitiesdiscovercallsame capabilitiescompletechargepayment tokenAgentthe platformWalletcredential provider/.well-known/ucpprofile: capabilities, handlers, keysRESTMCPA2AEmbeddedCatalogCartCheckoutOrderPayment handlershow the store accepts a tokenPSPprocesses payment

The site has two tabs, not four tracks

The top navigation is Overview (six short pages) and Specification (the versioned spec). The four audience cards on the homepage are just links:

CardWhere it actually goes
For DevelopersThe specification overview ↗
For BusinessesOff-site, to Google's merchant docs ↗
For AI PlatformsCore Concepts ↗
For Payment ProvidersUCP and AP2 ↗

Learn the roles first

Defined by direction of flow, not by industry. Every page assumes them.

PlatformConsumes capabilities. The agent, app or search engine acting for the buyer.
BusinessExposes capabilities, and is the Merchant of Record: it keeps the liability and owns the order.
BuyerThe person. The glossary has no separate User or Agent entry.
Credential ProviderA wallet. Holds the payment and identity credentials.
PSPProcesses the payment for the business.

The pattern that halves the reading

The spec is organized by capability, and every capability repeats the same pages. Once you have read one Overview and one binding, the rest are the same payload in another envelope.

Capability   (Catalog, Cart, Checkout, Order, Location, Permalink)
  ├── Overview    the data model and rules      ← read
  ├── REST        same capability over HTTP     ← read one binding
  ├── MCP         same, as JSON-RPC tools
  ├── A2A         same, agent to agent          (Checkout only)
  └── Embedded    same, in an iframe or webview
RESTIdempotency-Key, Request-Id and UCP-Agent headers. Permalinks are REST only.
MCPEach operation is a tool. Headers move into arguments.meta; id sits beside checkout.
A2ANo fixed operations. Messages or data parts, state in contextId.
EmbeddedNot an API: the store's own checkout in an iframe, over postMessage.

Read these five, in order

About two hours. Everything else is lookup.

  1. 01Glossary ↗Not in the sidebar, and the cheapest page on the site.
  2. 02Core Concepts ↗Capability vs extension vs service, and the profile.
  3. 03Specification Overview ↗Discovery, negotiation and the error taxonomy.
  4. 04Checkout ↗The state machine, totals and message severity. The densest page; reread it.
  5. 05One binding ↗REST if you are server to server.

Then go as deep as your role

DeveloperThe five pages above, then your binding, then Reference for the schemas.
BusinessCheckout, the payment handler choice, Fulfillment and Discounts. Then Google's merchant docs.
Payment providerPayment guide, Tokenization, the three handler examples, AP2 Mandates, Signatures.
AI platformCore Concepts, negotiation in the Overview, the MCP and A2A bindings, 3DS.

The checkout, in one picture

The page that repays rereading, reduced to its states.

Architecture diagramComponents: incomplete, ready_for_complete, completed, requires_escalation, complete_in_progress, canceledinputs validcompleteasync paymentdoneneeds a humanresolvedincompleteready_for_completecompletedrequires_escalationcomplete_in_progresscanceledreachable from any state

Six traps, before you write code

Failure can arrive as HTTP 200

Business outcomes come back with messages and a 200. Read ucp.status, not the status code.

Update means replace

Cart and checkout updates replace the whole resource. Send all of it or lose fields.

Versions match exactly

Every dev.ucp.* entry carries the profile's date. Upgrading is restamping, not bumping.

complete_in_progress is a lock

No update, no second complete. Only poll, with backoff.

Totals are the store's

Render every line in order. If the sum does not check out, do not fix it and do not complete.

Headless agents cannot do 3DS

A challenge needs a real browser view. With none, the only path is handing off to continue_url.

Versions and what is missing

Releases are dated snapshots: 2026-01-11, 2026-01-23, 2026-04-08 and 2026-08-25, with /latest/ pointing at the newest. Not in the spec yet: Food is coming soon, Lodging is draft only, and cross-sell, store pickup and the India, APAC and LatAm rollout are roadmap.

Loading it into a model? The whole site is published as llms-full.txt ↗, and any page works with .md appended.

How UCP compares with ACP, AP2 and the rest is on the protocols page.