Skip to main content

​
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

RoleDescriptionExamples
Business (Merchant)The seller providing goods and services; deploys the UCP ProfileIndependent e-commerce sites, brand websites
PlatformThe e-commerce platform hosting merchants; hosts UCP capabilities on their behalfShopify, Etsy, Wayfair
AI AgentThe AI system acting on behalf of the consumer to complete purchasesChatGPT, Claude, Gemini
ConsumerThe person ultimately purchasing the goodsThe end user of the AI agent
Payment HandlerThe service provider processing payment token exchangeStripe, 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:
StateMeaning
incompleteSession created but information is incomplete
requires_escalationHuman intervention needed (e.g., age verification, high-risk orders)
ready_for_completeAll information is ready; session can be submitted
complete_in_progressCompletion request is being processed
completedTransaction successfully completed
canceledTransaction 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: 
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: 
{
  "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: 
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)
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:
TransportSchemaCommunication ModelTypical Use Case
RESTOpenAPI 3.xHTTP request/responseServer-side integration, platform interoperability
MCPOpenRPC (JSON-RPC 2.0)Tool invocationDirect AI application integration (search_catalog, lookup_catalog, get_product)
A2AAgent Card SpecificationAgent-to-agent messagingMulti-agent collaboration (shopping agent + payment agent)
EmbeddedOpenRPC schemaEmbedded invocationAI 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

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 — 6 states, 5 operations, embedded UI, and ISO 4217 amount handling