> ## Documentation Index > Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt > Use this file to discover all available pages before exploring further. # UCP protocol architecture and core concepts > UCP protocol architecture in depth — namespace governance, four core capabilities, UCP Profile, capability negotiation, and transport. # UCP Core Concepts ## 1.1 The Role of UCP UCP is the end-to-end protocol for AI agent commerce — covering product discovery, transactions, and payments. The core problem it solves: **how can an AI agent safely complete a full commercial transaction with a merchant?** In traditional e-commerce, a consumer opens a website, browses products, adds items to a cart, and checks out. UCP standardizes this entire flow as protocol capabilities, enabling AI agents to programmatically complete the full purchase lifecycle — from product discovery to checkout, identity linking to order tracking, payment negotiation to token exchange. UCP was co-developed by **Google, Shopify, Etsy, Wayfair, Target, and Walmart**, with 30+ ecosystem partners (including Adyen, Affirm, American Express, Ant International, Best Buy, Block, Klarna, PayPal, Stripe, and Visa). It is open-sourced on GitHub under the Apache 2.0 license. ## 1.2 Participant Roles | Role | Description | Examples | | ----------------------- | --------------------------------------------------------------------------------- | -------------------------------------------- | | **Business (Merchant)** | The seller providing goods and services; deploys the UCP Profile | Independent e-commerce sites, brand websites | | **Platform** | The e-commerce platform hosting merchants; hosts UCP capabilities on their behalf | Shopify, Etsy, Wayfair | | **AI Agent** | The AI system acting on behalf of the consumer to complete purchases | ChatGPT, Claude, Gemini | | **Consumer** | The person ultimately purchasing the goods | The end user of the AI agent | | **Payment Handler** | The service provider processing payment token exchange | Stripe, Adyen, PayPal | **Merchant-Centric Principle**: UCP is designed to ensure that merchants always retain control. The merchant is the Merchant of Record, responsible for product pricing, inventory management, and order fulfillment. The AI agent acts as a representative of the consumer — it is not a party to the transaction. Platforms host UCP capabilities on behalf of merchants, but merchants retain ultimate control over business rules. ## 1.3 Four Core Capabilities UCP uses reverse-domain namespaces to identify each capability, ensuring global uniqueness and preventing naming conflicts. ### Checkout **Namespace**: `dev.ucp.shopping.checkout` Checkout is UCP's core transaction capability. A checkout session follows a well-defined state machine: | State | Meaning | | ---------------------- | -------------------------------------------------------------------- | | `incomplete` | Session created but information is incomplete | | `requires_escalation` | Human intervention needed (e.g., age verification, high-risk orders) | | `ready_for_complete` | All information is ready; session can be submitted | | `complete_in_progress` | Completion request is being processed | | `completed` | Transaction successfully completed | | `canceled` | Transaction has been canceled | Five operations are supported: **Create** (create session), **Get** (query session), **Update** (update information), **Complete** (submit for completion), and **Cancel** (cancel session). All monetary amounts use **ISO 4217 minor units** (e.g., USD uses cents, JPY uses yen directly). ### Identity Linking **Namespace**: `dev.ucp.common.identity_linking` Built on the **OAuth 2.0 Authorization Code** flow. Merchants publish authorization server metadata via `/.well-known/oauth-authorization-server`. The standard scope is `ucp:scopes:checkout_session`. Token revocation (RFC 7009) is supported, allowing users to revoke AI agent access at any time. ### Order Management **Namespace**: `dev.ucp.shopping.order` Line item status tracking: `processing`, `partial` (partially fulfilled), `fulfilled`, and `removed`. Fulfillment event types: `processing`, `shipped`, `in_transit`, `delivered`, `attempted_delivery`, `ready_for_pickup`, `picked_up`, and more. Adjustment types: `refund`, `return`, `credit`, and others. Webhook notifications use **RFC 9421 HTTP Message Signatures** to ensure data integrity. ### Payment Token Exchange Payment processors use reverse-DNS naming (e.g., `com.stripe.payment`). The lifecycle consists of three steps: 1. **Negotiation**: The platform and merchant determine mutually supported payment processors 2. **Acquisition**: The platform obtains payment credentials 3. **Completion**: Credentials are used to complete the payment Credential flow is **unidirectional**: from platform to merchant (Platform to Business), ensuring payment security. ## 1.4 Namespace Governance UCP namespaces use the reverse-domain format to ensure global uniqueness: ```text theme={null} Format: [reverse-domain].[service].[capability] UCP official namespaces: dev.ucp.shopping.checkout # Checkout capability dev.ucp.common.identity_linking # Identity linking dev.ucp.shopping.order # Order management dev.ucp.shopping.buyer_consent # Buyer consent (extension) dev.ucp.shopping.ap2_mandate # AP2 mandate (extension) Vendor namespaces: com.shopify.custom_checkout # Shopify custom com.stripe.payment # Stripe payment processor ``` **Governance rules**: * `dev.ucp.*` namespaces are managed by UCP official and must originate from `https://ucp.dev/` * `com.vendor.*` namespaces are self-managed by each vendor * Namespaces ensure that extensions from different vendors never conflict ## 1.5 UCP Profile (/.well-known/ucp) Every UCP-enabled merchant or platform must publish a JSON Profile document at the `/.well-known/ucp` path. This is the entry point for AI agent discovery and integration. **Key requirements**: * Must be served over **HTTPS** (HTTP is not permitted) * **No redirects allowed** (3xx responses will be rejected) * Must set `Cache-Control` header: `public, max-age` of at least 60 seconds The Profile document contains the following core fields: ```json theme={null} { "supported_versions": ["2026-04-08"], "services": { "dev.ucp.shopping": { "base_url": "https://store.example.com/ucp" } }, "capabilities": { "dev.ucp.shopping.checkout": { "version": "2026-04-08", "supported_operations": ["create", "get", "update", "complete", "cancel"] }, "dev.ucp.common.identity_linking": { "version": "2026-04-08" }, "dev.ucp.shopping.order": { "version": "2026-04-08" } }, "payment_handlers": [ "com.stripe.payment", "com.adyen.payment" ], "signing_keys": [ { "kid": "key-2026-04", "kty": "EC", "crv": "P-256", "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU", "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0", "use": "sig", "alg": "ES256" } ] } ``` ## 1.6 UCP-Agent HTTP Header When communicating with merchants, AI agents use the `UCP-Agent` HTTP header to declare their identity. The header follows the **RFC 8941 Dictionary Structured Field** format: ```http theme={null} UCP-Agent: profile="https://agent.example/profiles/shopping-agent.json" ``` This allows merchants to identify which AI agent is making the request, facilitating logging, rate limiting, and trust management. ## 1.7 Capability Negotiation Algorithm When an AI agent and a merchant first establish a connection, they must negotiate to determine mutually supported capabilities. The algorithm has four steps: 1. **Compute intersection**: Find capabilities with matching names in both Profiles 2. **Select version**: For each shared capability, choose the highest version supported by both parties 3. **Prune orphaned extensions**: Remove extensions that depend on capabilities not in the intersection 4. **Repeat pruning**: Execute step 3 repeatedly until no more extensions are removed (stable state reached) ```text theme={null} Example: Agent supports: checkout v2026-04-08, identity v2026-04-08, buyer_consent v2026-04-08 Merchant supports: checkout v2026-04-08, order v2026-04-08, buyer_consent v2026-04-08 Step 1 - Intersection: checkout, buyer_consent Step 2 - Version: checkout v2026-04-08, buyer_consent v2026-04-08 Step 3 - Prune: buyer_consent depends on checkout (in intersection), keep Step 4 - Stable: no further changes Final result: checkout v2026-04-08, buyer_consent v2026-04-08 ``` ## 1.8 Transport Mechanisms UCP is not bound to a single transport protocol. It supports four transport mechanisms: | Transport | Schema | Communication Model | Typical Use Case | | ------------ | ------------------------ | ------------------------ | ------------------------------------------------------------------------------------- | | **REST** | OpenAPI 3.x | HTTP request/response | Server-side integration, platform interoperability | | **MCP** | OpenRPC (JSON-RPC 2.0) | Tool invocation | Direct AI application integration (`search_catalog`, `lookup_catalog`, `get_product`) | | **A2A** | Agent Card Specification | Agent-to-agent messaging | Multi-agent collaboration (shopping agent + payment agent) | | **Embedded** | OpenRPC schema | Embedded invocation | AI capabilities embedded within merchant pages | ## 1.9 Versioning Strategy UCP uses **date-based version numbers** (e.g., `2026-04-08`) rather than traditional semantic versioning. This strategy offers several advantages: * Version numbers directly reflect the spec release date, making the timeline easy to understand * Each capability can be versioned independently * Capability negotiation uses simple date comparison to determine the latest version ## 1.10 A Complete Transaction Flow ```text theme={null} 1. AI agent fetches the merchant's /.well-known/ucp Profile 2. Runs the capability negotiation algorithm to determine mutually supported capabilities 3. If identity_linking is supported, links user identity via OAuth 2.0 4. Searches the product catalog via MCP or REST 5. Creates a checkout session (state: incomplete) 6. Updates buyer information, shipping method, and payment details 7. Session state transitions to ready_for_complete 8. Calls the Complete operation; state transitions to complete_in_progress 9. Transaction completes; state transitions to completed 10. Tracks fulfillment status via the order capability; receives webhook notifications ``` *** **Next chapter**: [Checkout API](/en/book-3/ch2-checkout) — 6 states, 5 operations, embedded UI, and ISO 4217 amount handling