Core Concepts

Overview

UCP addresses commercial interoperability through a three-layer abstraction model:

Service: Defines API surface and transport bindings
Capability: Declares supported functional features
Extension: Optional capability enhancement modules

This design keeps UCP’s core concise while supporting vertical domain extensions.

Participant Roles

UCP defines four main participant types, each with clear responsibilities:

Role	Responsibility	Examples
Platform	Discover business capabilities, initiate checkout sessions, present UI to users	AI shopping assistants, super apps, search engines
Business	Expose commerce capabilities, fulfill orders, process payments	Retailers, airlines, hotel groups
Credential Provider	Securely manage user sensitive data, issue payment tokens	Google Wallet, Apple Pay
Payment Service Provider	Handle payment authorization, clearing, settlement	Stripe, Adyen, PayPal

Key Design Principles

Business as Merchant of Record: Businesses retain financial responsibility and order ownership
Platforms don’t touch raw payment data: Minimize PCI-DSS compliance scope through tokenization
One-way credential flow: Payment credentials flow only from platform to business, never back

Service Layer

Service defines the API surface for a vertical domain (like shopping, common), including:

Field	Description	Example
`version`	Service version (YYYY-MM-DD format)	`2026-01-11`
`spec`	Service documentation URL	`https://ucp.dev/specification/overview`
`rest`	REST transport binding (optional)	OpenAPI 3.x spec
`mcp`	MCP transport binding (optional)	OpenRPC spec
`a2a`	A2A transport binding (optional)	Agent Card URL
`embedded`	Embedded transport binding (optional)	OpenRPC spec

Transport Binding Example

{
  "rest": {
    "schema": "https://ucp.dev/services/shopping/rest.openapi.json",
    "endpoint": "https://business.example.com/api/v2"
  }
}

Naming Convention

All Service and Capability names use reverse domain format:

{reverse-domain}.{service}.{capability}

Examples:

Name	Authority	Service	Capability
`dev.ucp.shopping.checkout`	ucp.dev	shopping	checkout
`dev.ucp.common.identity_linking`	ucp.dev	common	identity_linking
`com.example.payments.installments`	example.com	payments	installments

Capability Layer

Capability is an independent functional feature within a Service.

Capability Definition

Field	Required	Description
`name`	Yes	Capability name (reverse domain format)
`version`	Yes	Capability version (YYYY-MM-DD format)
`spec`	Yes	Specification document URL
`schema`	Yes	JSON Schema URL
`extends`	No	Parent capability name (for extensions)

Standard Capabilities

UCP defines the following core capabilities:

Capability	Description
Checkout	Checkout session management, including cart and tax calculation
Identity Linking	OAuth 2.0-based identity linking
Order	Order lifecycle event notifications

Extension Layer

Extension is an optional capability enhancement module, declaring a parent capability via the extends field.

Extension Example

{
  "name": "dev.ucp.shopping.fulfillment",
  "version": "2026-01-11",
  "spec": "https://ucp.dev/specification/fulfillment",
  "schema": "https://ucp.dev/schemas/shopping/fulfillment.json",
  "extends": "dev.ucp.shopping.checkout"
}

Extension Types

Extension	Description	Extends
Fulfillment	Delivery fulfillment	Checkout
Discount	Discount offers	Checkout
AP2 Mandates	AP2 encrypted payment instructions	Checkout

Profile: Configuration File

Profile is a JSON document published by participants at /.well-known/ucp, declaring identity, supported capabilities, and endpoints.

Business Profile Example

{
  "ucp": {
    "version": "2026-01-11",
    "services": {
      "dev.ucp.shopping": {
        "version": "2026-01-11",
        "spec": "https://ucp.dev/specification/overview",
        "rest": {
          "schema": "https://ucp.dev/services/shopping/rest.openapi.json",
          "endpoint": "https://business.example.com/ucp/v1"
        }
      }
    },
    "capabilities": [
      {
        "name": "dev.ucp.shopping.checkout",
        "version": "2026-01-11",
        "spec": "https://ucp.dev/specification/checkout",
        "schema": "https://ucp.dev/schemas/shopping/checkout.json"
      }
    ]
  },
  "payment": {
    "handlers": [...]
  },
  "signing_keys": [...]
}

Capability Negotiation

UCP uses a “server-selection” architecture for capability negotiation:

Platform declaration: Declare Profile URI via UCP-Agent header or request body
Capability intersection: Business calculates intersection of platform and business capabilities
Prune orphaned extensions: Remove extensions whose parent capability is not in the intersection
Response declaration: Business includes active capability list in response

Negotiation Flow

Platform Profile → Business Profile → Intersection Calculation → Active Capabilities
     [A, B]           [A, C]              [A]              [A]

Transport Protocols

UCP is transport-agnostic, supporting multiple protocols:

Transport	Use Case	Spec Format
REST	Standard application integration	OpenAPI 3.x
MCP	Direct LLM agent invocation	OpenRPC
A2A	Agent-to-agent collaboration	Agent Card
Embedded	Embedded business UI	OpenRPC

Next Steps

Specification Overview: Complete technical definition
Architecture Design: Discovery, negotiation, and payment architecture details

Architecture