mkdocs.yml

---
#   Copyright 2026 UCP Authors
#
#   Licensed under the Apache License, Version 2.0 (the "License");
#   you may not use this file except in compliance with the License.
#   You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#   Unless required by applicable law or agreed to in writing, software
#   distributed under the License is distributed on an "AS IS" BASIS,
#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#   See the License for the specific language governing permissions and
#   limitations under the License.


site_name: Universal Commerce Protocol (UCP)
# Required for the llmstxt plugin to work.
site_url: !ENV [SITE_URL, "https://ucp.dev/"]
site_description: >
  The Universal Commerce Protocol (UCP) is a solution for enabling gen AI agents
  to make payments on behalf of users, safely, securely, and in a decentralized
  and privacy protecting manner. This protocol is a part of the broader
  ecosystem, which includes agentic protocols like A2A and MCP, and encompasses
  the global nature of payments.
site_dir: site
edit_uri: edit/main/docs/

# Navigation
nav:
  - Overview:
      - Home: index.md
      - Core Concepts: documentation/core-concepts.md
      - Specification: !ENV [
          SPEC_URL,
          "https://ucp.dev/latest/specification/overview/",
        ]
      - UCP and AP2: documentation/ucp-and-ap2.md
      - Roadmap: documentation/roadmap.md
      - Schema Authoring: documentation/schema-authoring.md
      - Versioning: versioning.md
  - Specification:
      - Overview: specification/overview.md
      - Checkout Capability:
          - Overview: specification/checkout.md
          - Transports:
              - REST: specification/checkout-rest.md
              - MCP: specification/checkout-mcp.md
              - A2A: specification/checkout-a2a.md
              - Embedded: specification/embedded-checkout.md
          - AP2 Mandates Extension: specification/ap2-mandates.md
          - Buyer Consent Extension: specification/buyer-consent.md
          - Discounts Extension: specification/discount.md
          - Fulfillment Extension: specification/fulfillment.md
          - Loyalty Extension: specification/loyalty.md
          - Split Payments Extension: specification/split-payments.md
      - Cart Capability:
          - Overview: specification/cart.md
          - Transports:
              - REST: specification/cart-rest.md
              - MCP: specification/cart-mcp.md
              - Embedded: specification/embedded-cart.md
      - Catalog Capability:
          - Overview: specification/catalog/index.md
          - Search: specification/catalog/search.md
          - Lookup: specification/catalog/lookup.md
          - Transports:
              - REST: specification/catalog/rest.md
              - MCP: specification/catalog/mcp.md
      - Order Capability:
          - Overview: specification/order.md
          - Transports:
              - REST: specification/order-rest.md
              - MCP: specification/order-mcp.md
      - Identity Linking Capability: specification/identity-linking.md
      - Payment Handlers:
          - Guide: specification/payment-handler-guide.md
          - Template: specification/payment-handler-template.md
          - Tokenization Guide: specification/tokenization-guide.md
          - Examples:
              - Processor Tokenizer: "specification/examples/\
                  processor-tokenizer-payment-handler.md"
              - Platform Tokenizer: "specification/examples/\
                  platform-tokenizer-payment-handler.md"
              - Encrypted Credential: "specification/examples/\
                  encrypted-credential-handler.md"
      - Signatures: specification/signatures.md
      - Reference: specification/reference.md
      - Playground: specification/playground.md

repo_name: UCP on GitHub # Override repo name to be shorter on site header.
repo_url: https://github.com/Universal-Commerce-Protocol/ucp

# Copyright
copyright: >-
  Copyright 2026 UCP Authors. Licensed under the <a
  href="https://github.com/Universal-Commerce-Protocol/ucp/blob/main/LICENSE"
  >Apache License, Version 2.0</a>.

# Custom CSS
extra_css:
  - stylesheets/custom.css

#Global Constants
extra:
  ucp_version: "draft"
  ucp_url: https://ucp.dev
  analytics:
    provider: google
    # cSpell:disable
    property: G-ZEGTBCTMJ9
    # cSpell:enable
  consent:
    title: Cookie consent
    description: >-
      We use cookies to recognize your repeated visits and preferences, as well
      as to measure the effectiveness of our documentation and whether users
      find what they're searching for. With your consent, you're helping us to
      make our documentation better.
  scope: /
  version:
    provider: mike

# Configuration
theme:
  logo: assets/UCP-small.svg
  favicon: assets/favicon.png
  name: material
  font:
    text: Google Sans
    code: Roboto Mono
  icon:
    repo: fontawesome/brands/github
    view: material/pencil-box-multiple
    admonition:
      note: fontawesome/solid/note-sticky
      abstract: fontawesome/solid/book
      info: fontawesome/solid/circle-info
      tip: fontawesome/solid/bullhorn
      success: fontawesome/solid/check
      question: fontawesome/solid/circle-question
      warning: fontawesome/solid/triangle-exclamation
      failure: fontawesome/solid/bomb
      danger: fontawesome/solid/skull
      bug: fontawesome/solid/robot
      example: fontawesome/solid/flask
      quote: fontawesome/solid/quote-left
  palette:
    - scheme: default
      primary: white
      accent: indigo
    - scheme: slate
      primary: black
      accent: indigo
  features:
    - announce.dismiss
    - content.code.annotate
    - content.code.copy
    - content.code.select
    - content.tabs.link
    - content.tooltips
    # - navigation.expand
    - navigation.footer
    # - navigation.indexes
    # - navigation.instant
    # - navigation.instant.progress
    # - navigation.path
    - navigation.top
    - navigation.tracking
    - navigation.tabs
    - navigation.tabs.sticky
    - toc.follow

# Extensions
markdown_extensions:
  - meta
  - footnotes
  - admonition
  - attr_list
  - md_in_html
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets:
      base_path: .
      url_download: true
      dedent_subsections: true
      check_paths: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  - pymdownx.tasklist:
      custom_checkbox: true
  - toc:
      permalink: true

# Custom hooks
hooks:
  - hooks.py

# Plugins
plugins:
  - search
  - macros:
      on_error_fail: true
  - site-urls
  - social
  - llmstxt:
      full_output: llms-full.txt
      markdown_description: |
        This is the documentation directory for the Universal Commerce Protocol
        (UCP), an open standard that enables gen AI agents to safely, securely,
        and privately execute commerce actions (i.e., discovering, buying) on
        behalf of users.
        ### Technical Specification Indices (llms.txt)
        For raw, LLM-optimized indices of our versioned technical
        specifications:
        - [Latest Stable UCP
          Specification Index](https://ucp.dev/latest/llms.txt):
          Standardized specifications for production deployments.
        - [UCP Specification Index
          (2026-04-08)](https://ucp.dev/2026-04-08/llms.txt):
          Stable spec release version 2026-04-08.
        - [UCP Specification Index
          (2026-01-23)](https://ucp.dev/2026-01-23/llms.txt):
          Stable spec release version 2026-01-23.
        - [UCP Specification Index
          (2026-01-11)](https://ucp.dev/2026-01-11/llms.txt):
          Stable spec release version 2026-01-11.
      sections:
        Overview:
          - index.md: >-
              High-level architecture, core value propositions, and structural
              capabilities of the Universal Commerce Protocol (UCP) as a common
              language for commerce agents.
          - documentation/core-concepts.md: >-
              Fundamental UCP abstractions, including the decoupled separation
              of capabilities, extensions, services, and the decentralized
              protocol negotiation model.
          - documentation/ucp-and-ap2.md: >-
              Integration patterns with the Agent Payments Protocol (AP2) to
              facilitate secure, agent-mediated checkout commitments and
              cryptographically signed mandates.
          - documentation/roadmap.md: >-
              Future development and planned capabilities of UCP.
          - documentation/schema-authoring.md: >-
              Comprehensive guidelines and JSON Schema design conventions when
              authoring or extending UCP schemas, including strict versioning
              and registry patterns.
          - versioning.md: >-
              UCP's strict date-based versioning policy (YYYY-MM-DD) and
              compatibility guidelines for managing breaking changes and
              release branches.
        Specification:
          - specification/overview.md: >-
              Master technical specification of UCP, discovery mechanisms,
              secure transports, and error taxonomies.
        Message Signatures:
          - specification/signatures.md: >-
              Implementation details for RFC 9421 HTTP Message Signatures and
              RFC 9530 Content-Digests to achieve secure, transport-agnostic
              request authentication and replay protection.
        Checkout Capability:
          - specification/checkout.md: >-
              Core Checkout Capability specifications detailing session state
              lifecycles, totals calculation rules, and buyer input validation
              severity states.
          - specification/checkout-rest.md: >-
              HTTP REST transport binding for Checkout operations, specifying
              standard headers, API endpoints, status codes, and payload
              structures.
          - specification/checkout-mcp.md: >-
              Model Context Protocol (MCP) transport binding for Checkout
              operations, mapping UCP capabilities to JSON-RPC tools with
              agent metadata rules.
          - specification/checkout-a2a.md: >-
              Agent2Agent Protocol (A2A) binding for Checkout Capability,
              detailing transport discovery, agent card profile advertisement,
              and message negotiation flows.
          - specification/embedded-protocol.md: >-
              Core Embedded Protocol (EP) transport binding, defining message
              formats, handshake patterns, communication channels, security
              constraints, and shared error handling structures for
              iframe/webview integrations.
          - specification/embedded-checkout.md: >-
              Embedded Checkout Protocol (ECP) specification, detailing
              per-session delegation negotiation, URL parameters, native UI
              event mappings, W3C Payment Request conceptual alignment, and
              core lifecycle messages.
          - specification/ap2-mandates.md: >-
              AP2 Mandates Extension, detailing secure, cryptographically bound
              checkout commitments (using SD-JWT+kb digital credentials and
              detached JWS signatures) between business, platform, and payment
              providers.
          - specification/buyer-consent.md: >-
              Buyer Consent Extension, defining data schemas for transmitting
              buyer privacy choices (analytics, marketing, personalization) to
              assist with privacy compliance (CCPA/GDPR).
          - specification/discount.md: >-
              Discount Extension, covering discount code discovery, applied
              discounts, allocation method stacking orders, rejected code
              message handling, and automatic or provisional eligibility
              promotions.
          - specification/fulfillment.md: >-
              Fulfillment extension for checkouts, defining delivery methods,
              pickup destinations, and method-agnostic UI rendering contracts.
          - specification/loyalty.md: >-
              Loyalty Extension, enabling high-fidelity member benefit recognition
              during catalog, cart, and checkout by defining schemas for
              memberships, tiers, benefits, and reward earning forecasts while
              managing provisional eligibility claims and enforcing
              data-minimization privacy rules.
        Cart Capability:
          - specification/cart.md: >-
              Pre-purchase Cart Capability, detailing item collection, state
              modification, and seamless transition handoff to active checkout
              sessions.
          - specification/cart-rest.md: >-
              HTTP REST transport binding for Cart operations, including
              endpoints for session creation, modification, retrieval, and
              cancellation.
          - specification/cart-mcp.md: >-
              Model Context Protocol (MCP) transport binding for
              Cart operations, mapping item management to JSON-RPC
              tools for AI shopping agents.
          - specification/embedded-protocol.md: >-
              Core Embedded Protocol (EP) transport binding, defining message
              formats, handshake patterns, communication channels, security
              constraints, and shared error handling structures for
              iframe/webview integrations.
          - specification/embedded-cart.md: >-
              Embedded Cart Protocol (ECaP), enabling secure, cross-origin
              iframe communication and synchronized event states between
              platform agents and business websites.
        Catalog Capability:
          - specification/catalog/index.md: >-
              Core Catalog Capability, detailing high-level product discovery
              models, variant structures, merchant attribution, and real-time
              pricing context.
          - specification/catalog/search.md: >-
              Product discovery via the Search Catalog capability, specifying
              text queries, category browsing, and multi-attribute filtering
              contracts.
          - specification/catalog/lookup.md: >-
              Direct item retrieval via the Lookup Catalog capability,
              specifying variant resolution logic, batch identifiers,
              and interactive option selection.
          - specification/catalog/rest.md: >-
              HTTP REST transport binding for the Catalog Capability,
              detailing search, batch lookup, and product detail
              endpoints with JSON payload examples.
          - specification/catalog/mcp.md: >-
              Model Context Protocol (MCP) transport binding for the Catalog
              Capability, mapping discovery operations to JSON-RPC tools with
              metadata validation rules.
        Other Capabilities:
          - specification/order.md: >-
              Post-purchase tracking via the Order Capability, detailing line
              item updates, fulfillment expectations, shipment events,
              adjustments, and webhook-based status updates.
          - specification/order-rest.md: >-
              HTTP REST transport binding for the Order Capability, detailing
              endpoints, HTTP headers, payload schemas, and error structures.
          - specification/order-mcp.md: >-
              Model Context Protocol (MCP) transport binding for the Order
              Capability, detailing the JSON-RPC tool interface and parameters
              for fetching order states.
          - specification/identity-linking.md: >-
              User authentication via the Identity Linking Capability,
              specifying direct B2C/B2B OAuth 2.0 flows (with PKCE and
              RFC 9207) to unlock personalized commerce data.
          - specification/payment-handler-guide.md: >-
              Architectural framework and standard vocabulary for specifying UCP
              payment handlers, covering configuration declarations and
              transaction execution.
          - specification/payment-handler-template.md: >-
              Standard Markdown template and integration checklist
              when authoring new UCP payment handler specifications.
          - specification/tokenization-guide.md: >-
              Shared API, security requirements, and lifecycle policies
              (single-use, TTL, session-scoped) for building compliant
              tokenization payment handlers.
          - specification/examples/processor-tokenizer-payment-handler.md: >-
              Concrete payment handler example utilizing a 'Tokenize to Process'
              flow, where a single enterprise vault or PSP tokenizes
              credentials and resolves them internally.
          - specification/examples/platform-tokenizer-payment-handler.md: >-
              Concrete payment handler example utilizing a
              'Platform-as-Tokenizer' flow, where a platform's wallet
              generates tokens and hosts a secure detokenization endpoint.
          - specification/examples/encrypted-credential-handler.md: >-
              Concrete payment handler example utilizing a 'Direct Encryption'
              flow, where a platform encrypts payment data with a business's
              public key for local decryption.
          - specification/reference.md: >-
              Complete reference directory of all core UCP, type, and extension
              JSON schemas, including platform/business profiles and metadata
              objects.
          - specification/playground.md: >-
              Interactive, browser-based UCP Playground simulator for walking
              through step-by-step checkout sessions, payment handling, and
              backend webhooks.