DOCSEARCHbyAlgolia
Submit Docs

Universal Commerce Protocol (UCP) Documentation

repository·main·Indexed 25 days ago

https://github.com/universal-commerce-protocol/ucp

An open standard for interoperability between commerce platforms, businesses, Payment Service Providers (PSPs), and Credential Providers (CPs). UCP provides a standardized language and functional primitives for secure, agentic commerce integrations, featuring profile-based discovery, date-based versioning, and a decoupled 3-step payment lifecycle. It supports multiple transport bindings including REST, MCP, A2A, and Embedded.

Tokens
131.8K
Snippets
211
Records
499
Agent score
85%

What's inside Universal Commerce Protocol (UCP)

  1. Overview of Catalog Capability

    main

    The Catalog capability enables platforms to search and browse business product catalogs, facilitating product discovery before the checkout process. It supports several key use cases:

    • Free-text product search: Finding products via query text.
    • Category and filter-based browsing: Navigating via structured hierarchies and attributes.
    • Batch product/variant retrieval: Fetching specific items by their identifiers.
    • Price comparison: Comparing prices across different product variants.

    Catalog operations return product and variant IDs that are intended to be used directly in checkout line_items[].item.id fields. Note that catalog responses (pricing, availability, etc.) are not transactional commitments; the checkout process is the authoritative source for final terms.

  2. Overview of the Fulfillment Extension

    main

    The fulfillment extension allows businesses to advertise support for physical goods fulfillment (e.g., shipping, pickup) within the Universal Commerce Protocol. It integrates with two primary areas:

    1. Checkout (dev.ucp.shopping.checkout): Handles selection and cost, including which items go to which destination, the fulfillment method used, the price, and the ETA.
    2. Catalog (dev.ucp.shopping.catalog.search and dev.ucp.shopping.catalog.lookup): Enables discovery by allowing a product variant to advertise available fulfillment options based on buyer context.

    Fulfillment applies only to items requiring physical delivery; digital goods do not require fulfillment assignment.

  3. Overview of Universal Commerce Protocol (UCP)

    main
    The Universal Commerce Protocol (UCP) is a common language designed for platforms, agents, and businesses to enable agentic commerce. It provides standardized building blocks for the entire commerce lifecycle—from discovery to checkout—allowing different systems to operate through a single standard without requiring custom integrations for every new partner.

  5. Understand the Loyalty Extension core concepts

    main

    The Loyalty Extension enables high-fidelity loyalty experiences by allowing buyers to see their specific tier, eligible rewards, and applicable benefits during Catalog, Cart, and Checkout experiences. It addresses three main use cases:

    • Price-Impacting Benefits: Real-time application of member-only discounts and free shipping with clear attribution.
    • Non-Price Benefits: Transparent display of rewards earned or applicable to future purchases.
    • Status Recognition: Verification and display of the buyer's specific loyalty tier.

    Loyalty is composed of four main components:

    1. Memberships: Distinct enrollment pathways or program categories (e.g., a 'Rewards Club'). Multiple memberships are modeled as separate, namespaced sibling keys in the loyalty extension map.
    2. Tiers: Achievement ranks within a membership (e.g., 'Gold') that unlock escalating value.
    3. Benefits: Ongoing perks (e.g., 'dedicated customer service') or immediate-value perks (e.g., '5% off').
    4. Rewards: Quantifiable loyalty value earned from a transaction. Note that redeemable balances and stored value are handled by payment instruments, not this extension.

  6. Understand the UCP Actions concept

    main

    An Action is an outstanding unit of extension-defined work that a Platform must process. When an Action is present, the effect defined by its type is gated.

    Key characteristics:

    • Actions appear only in responses within the actions map.
    • An Action represents outstanding work and carries extension-owned processing configuration in a config object.
    • Actions are distinct from Messages; while a Message provides context, the Action identifies the work to be done.
    • A capability (like Cart, Checkout, or Catalog) only supports Actions if its specification explicitly adopts them.
    • For a successful response from a capability that adopts Actions, the Business MUST include every outstanding Action and MUST omit the actions key when none are outstanding.

  7. Understand the UCP Payment Architecture

    main

    UCP uses a decoupled architecture to manage the complexity between platforms, businesses, and payment credential providers. This design separates Payment Instruments (what is accepted) from Payment Handlers (how they are processed).

    The Trust Triangle

    1. Business ↔ Payment Credential Provider: A legal/technical relationship where the business holds API keys.
    2. Platform ↔ Payment Credential Provider: The platform acts as an intermediary to tokenize data (e.g., via an iframe) but does not own the funds.
    3. Platform ↔ Business: The platform passes the resulting token or mandate to the business to finalize the order.

    Roles & Responsibilities

    RoleResponsibilityAction
    Payment Credential ProviderDefines the SpecCreates the Handler Definition (JSON Schemas) for tokenization.
    BusinessConfigures the HandlerSelects a handler and provides Configuration (Public Keys, Merchant IDs) in the UCP Checkout Response.
    PlatformExecutes the ProtocolReads the business's config and executes the handler's logic to acquire a token.

  8. Understand the Order Capability (`dev.ucp.shopping.order`)

    main

    The Order capability represents confirmed transactions from successful checkouts. It provides a complete record of purchases, delivery methods, and post-order changes.

    Key components include:

    • Line Items: Details of what was purchased, including quantity counts and fulfillment status. Note that line items must include all items that ever existed on the order, even after edits.
    • Fulfillment: Tracks delivery via Expectations (buyer-facing promises about arrival) and Events (an append-only log of actual physical shipments).
    • Adjustments: Post-order events like refunds, returns, or credits. These are independent of fulfillment and should ideally be managed as an append-only ledger.

  9. Understand the Embedded Checkout Protocol (ECP) model

    main

    The Embedded Checkout Protocol (ECP) is a transport binding of the UCP Embedded Protocol (EP). It allows a host (e.g., an AI Agent app, Super App, or Browser) to embed a business's checkout interface (via iframe or webview).

    Key characteristics:

    • Bidirectional Communication: The host receives events as the buyer interacts with the checkout.
    • Delegation: The host can delegate specific user actions, such as address or payment selection, to provide a native experience.
    • Orchestration: Unlike the W3C Payment Request API where the browser orchestrates the flow, in ECP the business orchestrates the flow within the embedded context, with the host acting as an optional delegate for specific UI components.

  10. Key Features of UCP

    main

    UCP is designed with the following core principles:

    • Scalable and Universal: A surface-agnostic design that supports businesses of all sizes (small to enterprise) across all modalities, including chat, visual commerce, and voice.
    • Businesses at the Center: Designed to facilitate commerce while ensuring businesses retain control, remain the Merchant of Record, and maintain full ownership of customer relationships.

  11. Understand Payment Handler Core Concepts

    main

    The Payment Handler framework consists of several logical data flows and participants. Every handler specification must define these elements to ensure interoperability between businesses and platforms.

    Core Participants

    • Business: Advertises handler configuration and processes payment instruments. Note that technical schema fields may use merchant_* nomenclature (e.g., merchant_id).
    • Platform: Discovers handlers, acquires payment instruments, and submits the checkout.
    • Extended Participants (Optional): Such as a Tokenizer (stores credentials and issues tokens) or a PSP (processes payments on behalf of the business).

    Logical Data Flows

    1. Prerequisites: Onboarding and identity/config acquisition.
    2. Handler Declaration: Business advertising its configuration.
    3. Instrument Acquisition: Platform acquiring a payment instrument for checkout.
    4. Processing: Participant processing the instrument to complete a transaction.

  12. Understand the Buyer Consent Extension structure

    main

    The Buyer Consent extension allows businesses to communicate consent options and platforms to transmit buyer decisions regarding data usage and communication. Consent is structured in two levels:

    1. Purpose: The top-level intent (e.g., dev.ucp.consent.marketing). Each purpose includes a granted state, a source (who asserted the state), a description, and optional links.
    2. Segment: An optional refinement of a purpose that scopes it to a specific channel (e.g., email), vendor, or program. Segments have the same structure as a Purpose and override the parent purpose for that specific scope.

    Note: Nesting is limited to one level; segments cannot contain further nested segments.