Introduction to Universal Commerce Protocol Discovery

In the evolving landscape of agentic commerce, the ability for Large Language Models (LLMs) and autonomous agents to discover and interact with e-commerce infrastructure is paramount. The /.well-known/ucp endpoint serves as the foundational discovery mechanism for the Universal Commerce Protocol (UCP). Following the conventions established by RFC 8615, this endpoint provides a standardized, machine-readable entry point that allows agents-such as Google Gemini-to identify a merchant’s capabilities, supported payment gateways like Google Pay, and the specific Model Context Protocol (MCP) servers available for deep integration.
JSON Schema for UCP
The core of the /.well-known/ucp endpoint is a JSON document that defines the technical interface of the store. This schema is designed to be extensible, supporting both current REST API patterns and future agentic workflows. Developers must ensure the JSON response adheres to the following structural definition.
Top-Level Object Properties
| Specification Dimension | Legacy Robot/Sitemap Discovery | UCP Well-Known Manifest | Protocol Primitive | Security & CORS Policy | Agent Execution Impact |
|---|---|---|---|---|---|
| Manifest Resolution | robots.txt or XML sitemaps parsed asynchronously by web crawlers. | /.well-known/ucp.json RFC 8615 standardized endpoint. | HTTP GET /.well-known/ucp with application/json accept header. | Public read, CORS Allow-Origin: *, HSTS preloaded. | Sub-15ms deterministic machine discovery. |
| Capability Negotiation | None. Crawler infers capabilities from HTML markup. | Dynamic JSON-LD capability flags (checkout_v2, escrow, ap2). | Semantic capability declaration matrix in manifest body. | Merchant-signed attestation of supported commerce operations. | Agents select exact supported execution paths without trial-and-error. |
| Cryptographic Verification | Unsigned plaintext files susceptible to DNS spoofing and MITM. | Ed25519 / JWS signed domain signature header. | RFC 9421 Signature-Input over manifest payload hash. | DNSSEC-bound domain identity verification. | Guarantees authenticity of merchant endpoints and public keys. |
| Cache Invalidation | Unpredictable crawler re-index intervals (days to weeks). | ETag / 304 Not Modified with max-age=3600 & pub/sub. | RFC 9111 HTTP Caching with WebSocket invalidation channel. | Strict Cache-Control directives to prevent stale pricing. | Real-time capability synchronization across all AI shopping agents. |
| Endpoint Routing | Scattered deep links requiring natural language scraping. | Explicit URI mappings for catalog, cart, quote, and settle. | Structured REST / JSON-RPC URI endpoint dictionary. | Mutual TLS optional for high-value B2B procurement endpoints. | Eliminates scraping hallucination and broken checkout flows. |
Every profile carries ucp.version (REQUIRED, date YYYY-MM-DD). Current spec is v2026-08-25; Google merchant surfaces implement 2026-04-08.
Capabilities are named {reverse-domain}.{service}.{capability} (dev.ucp.* reserved to spec); payment lives under dev.ucp.common.payment.*, identity linking is dev.ucp.common.identity_linking, cart is dev.ucp.shopping.cart.
Defining Checkout Paths

The capabilities array informs the agent whether it can complete a transaction entirely via API (Native Checkout) or if it must hand off the user to a secure web view (Embedded Checkout). When ‘native_checkout’ is advertised, the agent expects a specific set of REST API endpoints to be available for cart creation, shipping estimation, and payment submission.
Merchant PSP must process Google tokens and merchant must provide Google Pay configuration inside UCP profile; allowed_auth_methods effectively PAN_ONLY in UCP checkout flow.
Example Payload
Profile advertises ucp.version, ucp.services, ucp.payment_handlers (entries carry id, version, spec, schema, available_instruments, config), and keys[]; platforms advertise profile URI in UCP-Agent header.
Hosting Requirements
For the /.well-known/ucp endpoint to be valid and discoverable by global agents, it must meet rigorous hosting standards. Failure to comply with these requirements will result in the merchant being flagged as ‘ineligible’ within the Google AI Mode ecosystem.
Protocol and Path
The file must be served exclusively over HTTPS at the root domain. Subdomains are permitted only if they are registered as distinct merchant entities in Google Merchant Center. The absolute path is: https://{domain}/.well-known/ucp. Redirection (HTTP 301/302) should be avoided to minimize latency during the agent’s initial discovery phase.
HTTP Headers
To ensure proper parsing and cross-origin accessibility, the following headers are mandatory:
- Content-Type: application/json; charset=utf-8
- Access-Control-Allow-Origin: * (or a whitelist of trusted agent domains)
High Availability
As this endpoint is the entry point for all agentic commerce, it should be hosted on a CDN or a highly available edge network. If a Gemini agent cannot reach this endpoint during a user’s purchase intent cycle, it will default to traditional search results rather than an autonomous checkout flow.
November 2026 update: Spec stays v2026-08-25; Google surfaces implement 2026-04-08. UCP-Agent/User-Agent are routing/analytics only — never authenticate on headers alone; verify RFC 9421 ES256 signatures against https://ucp.goog/.well-known/ucp.json plus mTLS to Google UCP Roots. Direct UCP checkout live US plus Canada shopper-side since Nov 4, 2026; Merchant Center self-serve integration follows in 2027.
Validation and Security
Security is a critical pillar of the UCP specification. The discovery file exposes the architectural layout of your commerce stack, necessitating robust protection against malicious actors while maintaining accessibility for verified agents.
Verifying Agent Identity
While the /.well-known/ucp file itself is public, the endpoints it references must be protected. Merchants should implement Identity Linking to correlate a user’s Google account with their internal customer record. This is typically achieved via OAuth 2.0. When an agent like Gemini makes a request to a UCP endpoint, it will provide a bearer token obtained through the authorization flow defined in the discovery file.
Risk Signals and Integrity
Model Context Protocol (MCP) Integration
REST is the recommended default transport; Merchant Center self-serve checkout validation supports only REST. Stateless MCP tools/call over HTTP POST is Early Access (Beta) requiring onboarding.
Integration with Google Ecosystem
Conclusion
Implementing the /.well-known/ucp endpoint is not merely a technical requirement; it is a strategic move into the future of Agentic Commerce. By providing a structured, secure, and standardized discovery path, developers enable their commerce platforms to be navigated by the next generation of AI agents, moving beyond the browser and into the era of seamless, intent-driven transactions.
Related UCP Guides & Technical Resources
- UCP Taxonomy Mapping: Align Categories for AI Discovery
- Machine Learning in Commerce: How AI Agents Learn Buyer Preferences
Frequently Asked Questions
Why does UCP standardize on the /.well-known/ RFC 8615 path?
The RFC 8615 well-known URI standard allows autonomous agents to discover commerce capabilities at the domain root without crawling HTML pages or guessing undocumented API endpoints.
How do agents verify that a /.well-known/ucp manifest has not been tampered with?
Production UCP manifests require RFC 9421 cryptographic signatures in HTTP headers, verifiable against public keys anchored in the merchant’s DNS TXT records and DNSSEC chain of trust.
What is the recommended caching policy for the UCP discovery endpoint?
The specification mandates a Cache-Control max-age of 3600 seconds with strong ETag validation, coupled with an optional WebSocket or Webhook pub/sub channel for instant cache invalidation upon catalog or policy updates.

Leave a Reply