01
Two documents published under one name
Applies to marketplace onlyown storefronthybrid
The first thing to establish about UCP is which document a given statement comes from, because two separate publications carry the name and they answer different questions.
One is a versioned technical specification covering discovery, capability negotiation, shopping, fulfillment, and payment handling.1 The other is Google’s integration documentation, which describes its own integration model, its native and embedded checkout paths, and where the merchant of record sits in each.2 The specification describes mechanisms. The integration documentation describes a program and the conditions attached to joining it.
These are not competing accounts, and neither supersedes the other. They cover different subject matter, so a question about how a negotiation resolves is answered by the specification, and a question about whether a particular seller can participate is answered by the program documentation. Four terms recur throughout both.
| Term | What it refers to | Where it appears in this lesson |
|---|---|---|
| Profile | A document published on a business’s own domain describing what that business supports | The discovery section below |
| Capability | A named, versioned feature, distinct from a protocol version | The negotiation section |
| Payment handler | A named specification describing how a payment is obtained, such as a wallet | The payment section |
| Merchant of record | The business a sale legally belongs to and that owes any refund | Documented per checkout path in the integration documentation |
02
The profile document a participating business publishes
Applies to marketplace onlyown storefronthybrid
Discovery in UCP starts with a document the business publishes at a fixed, predictable location on its own domain. The specification describes its contents: a date-based protocol version, a list of services bound to the transports they are reachable over, a map of named capabilities, a list of the payment handlers the business accepts, and an array of public keys used to verify signed messages.4
No registration step precedes this. A platform that has not previously interacted with the business can read the document and determine what the business supports from the document alone.
The specification also states how the document is served: over HTTPS, publicly cacheable, with a minimum cache lifetime of sixty seconds.1 A minimum cache lifetime sets a floor on how recent a reading platform’s copy is required to be, which means a change to what a business supports may not be reflected everywhere immediately.
The profile does not list products. It describes the capabilities of the business, not its inventory, so publishing one has no bearing on whether a specific item can be found. Product data is handled separately and is covered in the feed lessons of this course.
03
How the capability set for an exchange is decided
Applies to marketplace onlyown storefronthybrid
An arriving platform sends its own list of supported capabilities in a request header. The merchant side then compares that list against the capabilities in its published profile, retains only those both sides support, removes any extension whose parent capability did not survive the comparison, and states the resulting set explicitly in its response.4 The specification refers to this arrangement as server-selects: the active set is computed by the merchant side and communicated back.
The specification keeps this separate from protocol-version compatibility.1 The two answer different questions, and the difference is visible in how each one fails.
| Question | What settles it | How a negative answer appears |
|---|---|---|
| Can the two systems exchange messages at all? | Protocol version compatibility | An error at the start of the exchange |
| Is a specific named feature active for this exchange? | The capability intersection | The feature is absent from the stated set; the exchange continues without it |
| Is this business able to participate in the checkout program? | The program documentation, not the specification | No exchange takes place, because the business is not onboarded |
The middle row carries the operational consequence. A capability that is not shared is pruned and the exchange proceeds, so its absence is recorded in the stated set rather than raised as an error. A merchant checking only for errors would not see it.
04
How versions and changes are published
Applies to marketplace onlyown storefronthybrid
UCP version identifiers are dates. The specification documents that additive changes do not increment the identifier, so new capabilities can appear while the version stays the same. Changes that break existing implementations are labeled as breaking and are published with two weeks of notice before they take effect.4
Two things follow for anyone recording what they built against. An unchanged version identifier establishes that no breaking change has been published; it does not establish that the document is unchanged. And the notice period is two weeks, which is a fact about the publication schedule rather than about any individual reader — a notice reaches an implementer only if they are watching the channel it appears on.
05
Payment handlers and the merchant’s obligations
Applies to marketplace onlyown storefronthybrid
The specification separates two things that are often described with the same word. A payment handler is a named specification, carrying a reverse-domain identifier, describing how a payment is obtained; a business advertises the handlers it accepts. The instrument is what a platform holds after running a handler — a token or an encrypted object — and it is the instrument that arrives at the merchant side to be charged.4
Advertising a handler names an arrangement the business already has with a payment provider. The specification does not define payment methods itself and does not replace an existing processor relationship.
Three obligations sit on the merchant side.1
| Obligation on the merchant side | What it prevents |
|---|---|
| A credential is never returned in a response | A payment credential being emitted back through the interface that received it |
| A submitted handler is checked against the advertised list | Processing against a method the business did not advertise |
| The advertised handler list is filtered against the specific cart | Offering an arrangement that does not apply to the order in question |
The third obligation means the published profile states what a business can accept in principle, while what a buyer is offered for a particular order is decided by the merchant side at that moment. For a seller whose items vary widely in price — a single high-value camera body alongside low-value accessories — that distinction is the one that determines what appears at checkout for each.
06
Documented market eligibility and approval conditions
Applies to marketplace onlyown storefronthybrid
Reading the specification and participating in the checkout program are separate matters, and the merchant-facing documentation is where the conditions on the second are stated. It sets out market eligibility, onboarding steps, and product-attribute requirements for UCP-powered checkout: three markets are named — the United States, Canada, and Australia — a product must be eligible in one of them, the merchant or partner must be a participating one, and the rollout is described as phased and selective.3
Separately, the integration documentation describes embedded checkout as limited to specific approved merchants.2 That is a stated access condition rather than a projection, and it applies to that path regardless of what a business publishes in its profile.
For a seller outside the named markets, the documentation describes no available onboarding path at present. The product-attribute requirements are published separately from the eligibility criteria, so the attribute work can be read and applied independently of whether onboarding is currently open to a given business.
- Check the named markets against where items are eligible to be sold, which is not necessarily the same as where a business is willing to ship.
- Note that participation is documented as running through merchants and partners, which in many cases makes a hosting platform the party that decides.
- Read the product-attribute requirements as a separate document from the eligibility criteria.
- Record the date the eligibility section was read, since the rollout is described as phased.
07
Who publishes the profile in practice
Applies to marketplace onlyown storefronthybrid
The profile sits on a domain. For a seller using a hosted storefront, that domain, its routing, and its deployment belong to the platform, so the platform is the party that publishes the profile and populates it from settings the seller may or may not be able to view.
That places most of the questions in this lesson with a supplier rather than with an implementation. Four of them have short factual answers.
- Whether a profile exists for the storefront The profile is a single document at a predictable path, so this resolves to yes or no.
- Which capabilities it advertises Only shared capabilities survive the intersection, so the advertised list sets the upper bound on what an arriving platform will attempt.
- Which payment handlers are named in it Handlers are advertised rather than assumed, so an arrangement that is absent from the list is not available for selection.
- How the platform handles a published breaking change Breaking changes carry two weeks of notice, and a hosting platform receives that notice on behalf of the stores it serves. What reaches the individual seller is a matter of the platform’s own communications.
08
Recording where you currently stand
Applies to marketplace onlyown storefronthybrid
The output of this lesson is a short record of which questions have answers today and which do not. Rows keep an unanswered question visible. Below is the record for the Meridian camera, with unresolved cells left as they are.
| Question | Source of the answer | Status for this item | Review date |
|---|---|---|---|
| Does a profile exist for this storefront? | The hosting platform, in writing | Not established — asked, no reply yet | Set on the day the request was sent |
| Is this market on the eligibility list? | The merchant help documentation | No — the seller’s market is not among the three named | Quarterly, since the rollout is described as phased |
| Which payment handlers are advertised for this store? | Platform settings or platform support | Not established | Same request as the first row |
| Do the published product-attribute requirements pass on this item? | The item record, checked field by field | Partly — no manufacturer part number exists for a single vintage body | Whenever the item record changes |
Two rows read “not established” and one reads no. Those are answers, and they are the rows that determine what happens next: the unresolved ones become a support request, and the market row records a documented condition that no amount of preparation changes.
Dates matter differently by row. The specification carries a version identifier, so recording the version read is sufficient to compare later.1 The merchant documentation is continuously updated at the same address, so for that row the date it was read is the only marker available.3
09
What the documents currently state
Applies to marketplace onlyown storefronthybrid
The specification describes a profile document published on a business’s own domain, listing protocol version, services, capabilities, accepted payment handlers, and verification keys; a capability intersection computed by the merchant side and stated in the response; version identifiers that are dates and that move only for breaking changes, with two weeks of notice; and three obligations governing how payment handlers are checked and how credentials are handled.
The merchant-facing documentation describes market eligibility limited to three named markets, participation running through merchants and partners, product-attribute requirements, a rollout described as phased and selective, and embedded checkout limited to approved merchants.
The current sources do not include a documented production transaction through UCP-powered checkout for a specific merchant’s goods, and they do not state when the named markets or approval conditions will change. Where an entry in your own record has no answer, it reflects the state of the sources consulted on the date they were read.
10
Practice
Exercise
Place one item against the UCP requirements
- Note which of the two documents each thing you currently believe about UCP came from, and mark anything you cannot trace to either.
- Check one real item against the published product-attribute requirements, field by field, recording each gap and whether it is a data-entry issue or a property of the item.
- Ask your hosting platform whether a profile exists for your storefront and which payment handlers it names, and record the reply with its date.
- Build the four-row record for that item, leaving unanswered cells visibly unanswered.
Check yourself
Two systems agree on the protocol version and one expected feature does nothing. What does that indicate?
The capability was not in the shared set. The merchant side retains only capabilities both parties advertised and prunes the rest, so an unshared feature is absent from the stated set rather than reported as an error.
Does publishing a profile make a seller’s stock findable?
No. The profile describes what the business supports and contains no products. Whether an item can be found is handled by product data, which is a separate mechanism.
What does the sixty-second minimum cache lifetime govern?
How recent a reading platform’s copy of the profile is required to be. It sets a floor on cache duration, which means a change to what a business supports may not be reflected by every platform immediately.
Does advertising a payment handler mean adopting a new payment method?
No. A handler is a named specification for how a payment is obtained, and advertising one identifies an arrangement the business already holds. The instrument produced by running the handler arrives at the merchant side for processing through the existing provider.
What condition does the documentation state for embedded checkout?
That it is limited to specific approved merchants. This is an access condition stated in the integration documentation, separate from anything in the technical specification.
Progress is saved in this browser only. No account, nothing sent anywhere.
11
Common questions
Is UCP a Google product or an open protocol?
The technical specification is published, dated, and readable by anyone. The checkout program documented alongside it is Google’s and carries its own eligibility conditions. Statements about UCP are clearer when the document they come from is identified.
Does UCP replace a product feed?
No. The profile document contains no products, and product-attribute requirements are stated separately in the merchant documentation. The specification governs how systems exchange information; product data remains its own work.
What applies to a seller outside the listed markets?
The onboarding path described in the merchant documentation names three markets, so it does not currently describe a route for sellers elsewhere. The published product-attribute requirements are separate and can be read and applied independently.
How does UCP relate to ACP?
They are separate specifications with separate maintainers and separate publication states, and they make different structural choices — publishing a profile document is a different starting point from hosting a checkout interface. Neither document establishes interoperability with the other.
If a version identifier has not changed, is the specification unchanged?
Not necessarily. Additive changes are documented as not incrementing the identifier, so new capabilities can appear under a stable version. Only breaking changes move it, and those carry a stated two-week notice period.
12
Research and sources
Rules and platform policies change. These primary sources were reviewed on ; confirm the current position for your jurisdiction and account before acting.
Claim evidence
- The UCP specification is versioned and defines discovery, capability negotiation, shopping, fulfillment, and payment-handler models, and it keeps capability negotiation separate from protocol-version compatibility; it does not prove that a particular merchant or surface implements them.
- technical requirement. Supported by Universal Commerce Protocol official specification .
- Google’s UCP integration documentation states its integration model, its native and embedded checkout paths, and its merchant-of-record position, and describes embedded checkout as limited to specific approved merchants.
- current external fact. Supported by Universal Commerce Protocol .
- UCP-powered checkout is documented as applying to products with eligibility in the United States, Canada, and Australia and to participating merchants and partners, with availability described as phased and select, alongside stated product-attribute requirements.
- current external fact. Supported by About UCP and UCP-powered checkout .
- A business participating in UCP publishes a profile document at the path /.well-known/ucp whose ucp object carries a date-based version, a services list binding supported verticals to transports, a named capabilities map, a payment_handlers list, and a keys array of JWK public keys.
- technical requirement. Supported by Universal Commerce Protocol core concepts documentation , Universal Commerce Protocol official specification .
- Profiles are required to be served over HTTPS with a public Cache-Control directive and a minimum time-to-live of sixty seconds.
- technical requirement. Supported by Universal Commerce Protocol official specification .
- Negotiation follows a server-selects model: the business intersects its declared capabilities against the set a platform advertises in the UCP-Agent header, matches by name, takes the highest mutually supported version, prunes orphaned extensions, and declares the resulting active set in every response.
- technical requirement. Supported by Universal Commerce Protocol core concepts documentation , Universal Commerce Protocol official specification .
- Version identifiers are date-based, additive changes do not increment them, and breaking changes are marked with an exclamation prefix and carry two weeks of notice.
- technical requirement. Supported by Universal Commerce Protocol core concepts documentation .
- A payment handler is a named specification such as com.google.pay or dev.shopify.shop_pay that a business advertises, while a payment instrument is the token or encrypted payload a platform obtains by executing that handler against a credential provider and then submits onward for processing.
- technical requirement. Supported by Universal Commerce Protocol core concepts documentation .
- Credential flow is one-directional: a business is required not to echo credentials back in its responses, must confirm that a submitted handler identifier matches one it advertised, and must filter its advertised handler list against the contents of the cart in front of it.
- technical requirement. Supported by Universal Commerce Protocol official specification .
- Universal Commerce Protocol official specification Google · Tier A · published specification · 2026-04-08
UCP discovery, capability negotiation, shopping, fulfillment, and payment-handler models. Limit: The specification states interfaces and normative language; it does not prove that a particular merchant or surface implements them.
- Universal Commerce Protocol Google · Tier A · current documentation · unversioned live documentation
Google’s stated UCP integration model, native and embedded checkout paths, and merchant-of-record position. Limit: States Google’s own integration model. It does not establish that a given merchant is eligible, approved, surfaced, or transacting, and embedded checkout is described as limited to specific approved merchants.
- About UCP and UCP-powered checkout Google · Tier A · current documentation · unversioned live documentation
Stated market eligibility, onboarding steps, and product-attribute requirements for UCP-powered checkout. Limit: Applies only to products with eligibility in the United States, Canada, and Australia and to participating merchants and partners; availability is described as phased and select. Establishes documented requirements, never a placement or sales outcome.
- Universal Commerce Protocol core concepts documentation Google · Tier A · continuously updated documentation · unversioned documentation published alongside the dated specification
The business profile document and its fields, the capability negotiation algorithm, payment handlers and payment instruments, and signing-key discovery. Limit: Continuously updated documentation carrying no version identifier of its own, so a claim drawn from it is only accurate as at the date it was read; it describes mechanisms rather than establishing that any business publishes a profile or that any platform reads one.