Universal Commerce Protocol: UCP Guide for Merchants

Start with the commerce capability you need

Universal Commerce Protocol, or UCP, provides a common structure for commerce interactions rather than asking every participant to invent a separate integration for every counterpart. Its current documentation covers capabilities including catalog, cart, checkout, identity linking and order management. Choose the capabilities your actual product and route need; do not advertise an operation merely because the standard defines it. [1]

Our fictional merchant Cedar sells a downloadable research report for an illustrative $29. Sam permits an assistant to buy the current personal-use edition up to $35. The merchant needs a discoverable offer, current checkout terms, an appropriate payment route and delivery to the intended customer. That example is a teaching scenario, not a live product or tested transaction.

The merchant's existing services should remain authoritative. UCP support should not create a second price calculator or bypass a license restriction that applies on the ordinary website. The protocol adapter connects supported operations to those business rules and communicates the resulting state to the platform.

Read the business profile as a contract advertisement

The current UCP technical overview says businesses publish a profile at /.well-known/ucp. The profile is a JSON discovery document with a required ucp member. It describes protocol metadata, services and payment handlers, with capabilities represented according to the current specification. Implement that actual structure rather than an older launch-day example found in a blog. [2]

As checked on October 8, 2026, the overview requires ucp.version, ucp.services and ucp.payment_handlers. The services and payment handler registries remain present even when empty. It describes ucp.capabilities as optional, though useful commerce profiles normally advertise relevant capabilities. This distinction matters: do not present every field as universally required when the current specification says otherwise. [2]

The annotated map below uses documented paths and explains their purpose. It is not a full business profile payload. Values and exact supported versions must come from your implementation and the pinned official specification. A copied placeholder endpoint is not evidence that a merchant exposes a working service.

A conceptual discovery exchange is GET https://cedar.example/.well-known/ucp followed by a JSON profile whose ucp object declares the chosen version, services and payment_handlers, with relevant capabilities when advertised. The .example address is fictional and no service is being called here. Follow the official full example and its schema when building the actual document; this sentence deliberately omits required nested values rather than inventing a deployable payload.

Keep the profile aligned with the deployed services

A profile can advertise a transport and endpoint that the platform uses to interact with the business. The endpoint needs to exist and implement the declared contract. If you publish a capability before its backing service works, discovery can succeed while the first purchase fails. Treat profile updates as part of deployment and verification.

Use an appropriate cache and update policy consistent with the protocol and infrastructure. A stale profile can advertise a version or key that has changed. Plan how a platform learns about the updated document and how your server handles a request based on previously available metadata. Do not assume that changing a JSON file instantly changes every caller's cached view.

When removing a capability, consider existing sessions and orders. New discovery may stop advertising an operation while previously created purchases still require status and support. Preserve the necessary recovery path and communicate the applicable behavior. Disabling a distribution route should not erase the merchant's obligation to orders already accepted.

Negotiate compatible capabilities and versions

UCP's technical overview describes protocol version selection and capability negotiation. Compatibility is more specific than both sides using the word UCP. A platform and business need mutually supported versions and the capabilities and extensions required for their interaction. Validate requests and responses against the resulting supported contract. [2]

Pin the versioned contract used in your integration record. Do not infer that an example version in documentation is the only version every participant supports. The published profile and actual request context establish what your implementation advertises and uses. Keep old and current behavior distinguishable when supporting more than one version.

Test the case where no compatible version or capability exists. The platform should receive the protocol-defined outcome rather than an apparently successful response missing required behavior. Unknown compatibility is not permission for an assistant to guess which fields the merchant meant. Use deterministic schema and business validation.

Identity linking is distinct from purchase authority

A linked merchant account can help deliver the report to the right customer or apply an existing relationship. It does not automatically authorize every purchase. The agent still needs authority for the current item, amount and terms under the supported route. A personal license and a recurring team subscription are materially different actions even if the first payment looks similar.

UCP describes account-linking and payment architecture, and AP2 provides a compatible authorization layer with linked checkout and payment mandates. Use the applicable specifications for the actual mechanism. Do not fabricate a mandate from a conversational approval or infer unlimited payment permission from a successful account-linking result. [1] [4]

Keep customer data within the appropriate boundary. The profile is public discovery metadata, so it is not a place for secrets or customer purchase information. Order and account APIs still require their supported authorization. A public product identifier does not permit access to another customer's report entitlement.

Payment handlers connect the checkout to a supported route

UCP's payment architecture describes payment handlers and the relationship among the business, platform and credential provider. A merchant should identify which handler fits its provider and supported customer payment experience. The existence of a handler description does not prove that the merchant account or product can use it. [2]

Map the credential flow explicitly. Determine which participant obtains the credential, which submits it for processing and which verifies the financial result. Keep raw payment data out of model output and general-purpose logs. Follow the handler and provider's actual contract rather than designing a universal token field with guessed semantics.

For Cedar, the important result is a payment outcome tied to the $29 report order. If a payment step requires customer interaction, preserve a meaningful pending state and the correct continuation route. If the result is uncertain, resolve the existing attempt before another purchase. Those business requirements remain even when the protocol provides a standard interface.

Google surface requirements are an additional layer

Google's merchant guide describes Native and Embedded integration paths for its UCP experience. It also presents partner onboarding through a waitlist. The general protocol specification and Google's channel product are related, but they are not the same eligibility decision. A technically compatible merchant still needs current channel access for the intended surface. [3]

Check the actual seller country, buyer context, product type, account configuration and supported payment route in the current channel requirements. Do not use a general global-commerce statement as proof that all of those combinations are enabled. Where the public documentation does not answer your scenario, record an open onboarding question.

The guide also contains roadmap language alongside feature descriptions. Keep planned surface features distinct from the broader protocol's defined capabilities. If a particular Google experience has not established support for your required workflow, do not announce it to customers based on the protocol's theoretical scope.

• Documented in Google’s guide: Native is the default integration path; Embedded is optional for specific approved merchants.
• Documented onboarding: a partner waitlist is available. A working UCP profile alone does not establish admission.
• Protocol-defined, channel support to confirm: catalog, cart, identity linking and order capabilities must be checked against the exact Google experience. Roadmap language is not confirmation.
• Unknown for a particular merchant until checked: the seller/buyer country combination, product eligibility, chosen handler and account access.

Choose Native or Embedded by the real checkout needs

A native integration exposes the supported commerce operations to the platform's experience. An embedded path can preserve more of the merchant-controlled checkout interface under the relevant contract. Compare the actual supported behavior, customer interaction and operational boundaries rather than assuming one path is always simpler. [3]

For a simple report entitlement, a structured API route may align well with existing services. A product requiring specialized configuration or an unusual customer interaction may need a different supported path. The choice should follow the product's real requirements and channel support, not an aesthetic preference for keeping every action in a chat bubble.

Use the same acceptance scenario for both options. Verify the selected item, final total, authority, financial result and delivery. Include changed terms and uncertainty. A polished front-end demo is not enough if the underlying merchant records cannot explain the purchase afterward.

Keep verification keys and public metadata correct

The current UCP overview identifies top-level keys[] as the profile location for published public signing keys. It explains that the same profile can serve as a JWK Set and discusses key discovery and revocation. This is a specific current detail; do not use an invented signing_keys property or an obsolete example in a new implementation. [2]

Manage public key changes through your actual security and deployment process. Never publish private key material in a discovery document. Check the supported verification and rotation rules before changing a live key, and validate that callers use the intended source and context. This guide does not supply a complete signature implementation.

The business profile describes capabilities and verification metadata; it does not by itself prove a buyer's authority or a payment outcome. Maintain those checks at their proper boundaries. A well-formed profile should lead to an equally well-defined operational transaction, not replace one.

Treat extension support as a concrete implementation commitment. An extension can add required data or change validation at the capability boundary, so its presence should be reflected in the schema and the backing business service. Do not advertise an extension just because an example profile includes it. Test the actual negotiated combination and keep unsupported combinations explicit in the implementation record.

Test one documented end-to-end merchant flow

For Cedar, begin with profile discovery and compatible capability selection. Create the report checkout, update any required customer information and complete through the supported payment route. Confirm that the order grants access to the correct edition and that an authorized caller can retrieve the result.

Then test unsupported capability, incompatible version, changed amount, repeated completion and delivery failure. Record expected results using the exact pinned contract and merchant rules. These are recommended acceptance scenarios, not tests performed by this guide or certification of any participant.

Keep source dates, profile metadata, service ownership and recovery behavior in one integration record. Universal Commerce Protocol is useful when it makes the commerce boundaries explicit and interoperable. The merchant still needs an accurate offer, valid authority, accountable financial processing and fulfilment that can be explained to the buyer.