How to Implement UCP: The Native Build and Integrating via Rye

Twelve build steps from zero to a UCP-compliant merchant surface.

1. Publish /.well-known/ucp

The discovery profile. A signed JSON document at https://merchant.example/.well-known/ucp that declares which capabilities the merchant supports, where each capability is hosted, which transports it accepts, the merchant's public signing keys (in JWK format under signing_keys), and the payment handlers it advertises.

Spec-mandated operational properties:

• HTTPS only. All UCP communication MUST occur over HTTPS.

• Caching. Minimum 60-second TTL, Cache-Control: public.

• No redirects. Profile endpoints MUST NOT use 3xx responses.

The profile is the source of truth for what agents will call. It stays current as the merchant adds capabilities, rotates keys, or changes transports.

2. Stand Up RFC 9421 Signing Infrastructure

Every UCP response is signed with HTTP Message Signatures (RFC 9421). The merchant generates and rotates signing keys, publishes the public keys in the profile's signing_keys array, and signs every outbound response with Signature, Signature-Input, and Content-Digest headers.

Key rotation is coordinated across every UCP-serving service. The rotation window has to be long enough that in-flight agent calls can still verify the previous key.

3. Author JSON Schema Documents Per Capability

UCP uses JSON Schema 2020-12 for every payload. The merchant authors, hosts, and versions a schema document per declared capability. Schemas have to be reachable, valid 2020-12, and consistent with the actual server response — agents validate strictly, and the platform validates that the spec URI's origin matches the namespace authority (a security primitive the spec calls "namespace validation").

A typed catalog payload alone — product, variants, options, eligibility filters, availability, regulatory metadata — is often hundreds of fields, all of which the schema commits to.

4. Implement the Capability Intersection Algorithm

UCP uses a server-selects architecture for capability negotiation. When an agent connects, the merchant computes the intersection of platform-declared and business-supported capabilities through a defined algorithm:

1. Match capabilities by name; select the highest mutually-supported version

2. Prune extensions whose parent capabilities are absent

3. Repeat until the set is stable

4. Return the active capabilities in the response's ucp.capabilities object

The intersection shapes everything the agent attempts next. It also handles the merchant's evolution over time — capability additions, deprecations, version migrations.

5. Implement the Catalog Capability

Catalog covers two operations: dev.ucp.shopping.catalog.search and dev.ucp.shopping.catalog.lookup. Search returns matching products against an agent's query; Lookup returns the full product object for a specific product ID. Both are signed, both validate against the merchant's catalog schema, and both handle:

• Product variants with full option matrices and per-variant availability

• Real-time pricing — session-specific; the spec says catalog responses SHOULD NOT be reused across sessions without re-validation

• Eligibility filters (age-gated, regulated, region-restricted) via context.eligibility claims

• Media (images, video, optional 3D)

Catalog responses are explicitly not transactional commitments. Checkout is authoritative — pricing or availability can shift between catalog read and checkout creation.

6. Implement the Cart Capability

Cart is four operations: Create, Get, Update, Cancel. The merchant persists carts server-side, returns the full cart resource on every operation, and handles edge cases — out-of-stock items, eligibility shifts, optional expiry via the expires_at field.

Two spec requirements worth noting:

• Full-replacement updates. Update is a full replacement of the cart resource, not a patch. The platform sends the entire cart; the merchant replaces existing state.

• Cart-to-checkout idempotency. If an incomplete checkout already exists for a cart_id, the merchant MUST return the existing checkout session rather than create a new one.

There is no Delete operation. Cancel is the removal mechanism.

7. Implement the Checkout State Machine

The Checkout capability runs as a state machine over five REST operations on /checkout-sessions:

Three explicit states are defined in the spec: incomplete, ready_for_complete, and completed. A fourth — canceled — is implied by the /cancel operation.

State transitions handle address validation and normalization, real-time shipping calculation, real-time tax calculation, discount eligibility, payment handler selection, and final eligibility checks (region, age, regulated goods). The merchant returns a totals array on every response with the line-item-level breakdown (subtotal, tax, shipping, total).

The error model is two-tier:

• Protocol errors surface as HTTP status codes (401, 403, 409, 429, 503)

• Business outcomes return HTTP 200 with a messages array — each message carrying type, code, path, and severity (recoverable or unrecoverable)

For flows that can't complete headlessly — 3DS, captcha, age verification, ID upload — the response includes a continue_url. This is the merchant's existing checkout page.

8. Implement Payment Handlers

UCP doesn't process payments itself. It declares which payment handlers a merchant accepts — by reverse-DNS handler ID — and the merchant implements the server-side hooks for each declared handler. Spec-referenced handler IDs:

• com.google.pay

• dev.shopify.shop_pay

Each handler is its own integration with the merchant's PSP. The merchant advertises the handler in ucp.payment_handlers with its configuration; the platform supplies tokenized credentials. Token exchange, 3DS handling, refund flows, dispute response — per handler, per PSP relationship.

Payment handler implementation is selective. The merchant implements only the handlers it declares; undeclared handlers are unavailable.

9. Implement the Order Capability

Post-purchase. The merchant pushes order lifecycle updates to the platform via signed webhooks. Order covers two surfaces:

Fulfillment events — append-only is preferred per the spec ("Businesses SHOULD append new entries rather than mutating existing ones; append-only ledger is preferred"). Event type is an open string. Spec-listed examples: processing, shipped, in_transit, delivered, failed_attempt, canceled, undeliverable, returned_to_sender. Required fields per event: id, occurred_at, type, line_items.

Adjustments — for refunds, returns, credits, price changes, disputes, cancellations. Adjustments support in-place mutation as a fallback for businesses that don't maintain adjustment history ("MAY perform in-place updates").

Webhook payloads MUST be signed per RFC 9421. Retry semantics are at-least-once — the merchant MUST retry failed webhook deliveries. The spec does not currently mandate an idempotency-key mechanism, so the platform's redelivery handling is the operational guarantee.

The Order capability covers post-confirmation lifecycle only. "Placed" and "paid" are implicit in a successful Checkout /complete call — they are not Order events.

10. Stand Up an OAuth 2.0 Authorization Server

Identity Linking requires a full RFC 6749 OAuth 2.0 server using the Authorization Code flow. No delegated or federated alternative is in the spec.

The merchant hosts the standard endpoints:

• Authorization endpoint

• Token endpoint (with enforced client authentication)

• Revocation endpoint per RFC 7009

Discovery follows OAuth's own standard — the merchant publishes endpoint locations at /.well-known/oauth-authorization-server per RFC 8414.

Scopes map to capability operations. The spec example: ucp:scopes:checkout_session grants access to all CheckoutSession operations (Get, Create, Update, Cancel, Complete). The merchant's consent UI is the merchant's responsibility — the spec advises hiding scope complexity behind general consent language rather than enumerating per-operation rows.

Merchants that already operate an OAuth server for their own apps can extend scopes into it. Merchants that don't are building a full identity platform.

11. Decide the Embedded vs. Continue-URL Handoff

For flows that can't complete headlessly — 3DS, captcha, age verification, OAuth consent — the merchant either redirects the user to its existing checkout via continue_url or, if it advertises the embedded transport, lets the agent embed the merchant's existing checkout UI directly in an iframe/webview.

What the merchant ships here:

• No new pages for the embedded path. Embedded Checkout reuses the merchant's existing checkout at the continue_url. The merchant declares support by advertising the embedded transport in its profile, and the agent loads the URL with ec_* query parameters (ec_version, ec_auth, ec_delegate, ec_color_scheme).

• A handshake on load. The merchant's embedded checkout sends an ec.ready message confirming which delegations it accepted; subsequent state changes (ec.start, ec.line_items.change, ec.complete, etc.) fire to the host.

• A new OAuth consent page if Identity Linking is declared. The merchant needs an agent-facing consent page if it doesn't already have one for its existing apps.

12. Operational Discipline

Once the eleven preceding steps are shipped, ongoing operational requirements:

• Profile caching. 60-second minimum TTL, Cache-Control: public, no redirects.

• Rate limits per agent, per capability, per endpoint.

• Schema fidelity audits as the storefront evolves.

• Versioned capability migration — UCP ships date-based revisions; the merchant migrates forward.

• Signing key rotation cadence.

• Webhook delivery SLOs and retry monitoring.

• Unidirectional credentials discipline. Credentials flow Platform → Business only; businesses MUST NOT echo credentials back.

• Agent behavior monitoring — which agents are calling, at what cadence, with what error rates.

What the merchant gets

Agents that adopt UCP discover the merchant via /.well-known/ucp, negotiate capabilities, and transact directly against the merchant's signed endpoints. The merchant is a named UCP participant in the spec's discovery model, owns the agent-facing schema (a JSON Schema 2020-12 contract the merchant evolves on the spec's revision cadence), has full visibility into agent calls on its own infrastructure, and has no commission relationship layered into the agent flow.