Platform Integration Guide

8.1 The Role of Platforms

In the UCP architecture, a platform hosts UCP capabilities on behalf of merchants. Platform responsibilities include:

Deploying and maintaining the /.well-known/ucp Profile on behalf of each merchant
Implementing the capability negotiation algorithm to automatically negotiate with AI agents
Managing merchant signing keys and OAuth configurations
Handling platform-side logic in the payment token exchange

8.2 Implementing the Capability Negotiation Algorithm

When an AI agent connects to a platform for the first time, both parties must perform capability negotiation. Platforms must implement this four-step algorithm:

Step 1: Compute the Intersection

Identify capabilities that appear in both the AI agent’s and the platform’s Profile:

function computeIntersection(agentProfile, platformProfile) {
  const agentCaps = Object.keys(agentProfile.capabilities);
  const platformCaps = Object.keys(platformProfile.capabilities);

  return agentCaps.filter(cap => platformCaps.includes(cap));
}

// Agent supports: checkout, identity_linking, buyer_consent
// Platform supports: checkout, order, buyer_consent
// Intersection: checkout, buyer_consent

Step 2: Select Versions

For each shared capability, select the highest version supported by both parties (using date-based comparison):

function selectVersion(agentCap, platformCap) {
  const agentVersions = agentCap.supported_versions || [agentCap.version];
  const platformVersions = platformCap.supported_versions || [platformCap.version];

  const mutual = agentVersions.filter(v => platformVersions.includes(v));
  // Date strings can be compared lexicographically
  return mutual.sort().reverse()[0]; // highest version
}

Step 3: Prune Orphaned Extensions

Remove extensions that depend on capabilities not present in the intersection:

function pruneOrphans(negotiated, dependencyMap) {
  return negotiated.filter(cap => {
    const deps = dependencyMap[cap] || [];
    return deps.every(dep => negotiated.includes(dep));
  });
}

// buyer_consent depends on checkout (in intersection) -> keep
// ap2_mandate depends on checkout + identity (identity not in intersection) -> remove

Step 4: Repeat Pruning Until Stable

function negotiate(agentProfile, platformProfile, dependencyMap) {
  let result = computeIntersection(agentProfile, platformProfile);

  // Select version for each capability
  result = result.map(cap => ({
    name: cap,
    version: selectVersion(
      agentProfile.capabilities[cap],
      platformProfile.capabilities[cap]
    )
  })).filter(cap => cap.version); // remove capabilities with no shared version

  // Iteratively prune until stable
  let prev;
  do {
    prev = result.map(c => c.name);
    result = result.filter(cap => {
      const deps = dependencyMap[cap.name] || [];
      return deps.every(dep => prev.includes(dep));
    });
  } while (result.length !== prev.length);

  return result;
}

8.3 Namespace Management

Platforms can register their own vendor namespaces (com.vendor.*) alongside the standard UCP namespaces (dev.ucp.*) to offer proprietary capabilities:

{
  "capabilities": {
    "dev.ucp.shopping.checkout": {
      "version": "2026-04-08"
    },
    "com.shopify.abandoned_cart_recovery": {
      "version": "2026-01-15"
    },
    "com.shopify.loyalty_points": {
      "version": "2026-03-01"
    }
  }
}

Governance rules:

dev.ucp.*: Only the official UCP organization (https://ucp.dev/) may register and manage these
com.shopify.*: Only Shopify may register and manage these
If an AI agent does not recognize a vendor namespace, it is automatically skipped during negotiation

8.4 Shopify

Shopify is one of UCP’s six co-developers and is expected to offer native UCP support. Existing UCP-compatible foundations:

Storefront API already supports JSON product queries and cart management
Checkout API supports programmatic checkout
Customer Access Token mechanism closely resembles OAuth
Agentic Storefronts feature is a precursor to UCP

What you can do now:

Ensure product data is complete (title, description, price, inventory, images, SKU)
Enable the Storefront API
Deploy a /.well-known/ucp Profile (via a Shopify App or custom proxy)
Wait for Shopify’s official UCP plugin for one-click enablement

8.5 WooCommerce

WooCommerce’s REST API already provides much of the data capability UCP requires: Already available:

GET /wp-json/wc/v3/products — Product listing
GET /wp-json/wc/v3/products/{id} — Product details
GET /wp-json/wc/v3/orders/{id} — Order lookup

UCP adapter layer required:

AI Agent -> UCP-format request -> Adapter Layer (CF Worker/Node.js) -> WooCommerce API
                                    |
                                    +- Format conversion: WC format <-> UCP format
                                    +- /.well-known/ucp Profile
                                    +- OAuth 2.0 proxy (WC natively uses API Keys)
                                    +- Signing key management

Adapter deployment options:

Cloudflare Worker: Lightweight, global edge deployment, low latency
Standalone Node.js service: Full control, suitable for complex logic
WordPress plugin: Deep integration with WooCommerce

8.6 Custom-Built Stores

Custom-built stores have maximum flexibility and can implement all UCP endpoints directly:

Deploy the /.well-known/ucp Profile (refer to Section 7.2)
Implement the product catalog API (REST and/or MCP transport)
Implement the checkout state machine (6 states, 5 operations)
Generate ES256 signing keys and configure Webhooks
Implement OAuth 2.0 and order management as needed

8.7 Platform Comparison

Platform	Integration Path	Estimated Effort	Key Dependency
Shopify	Wait for official plugin or build a proxy	0.5-1 day (proxy)	Storefront API
WooCommerce	Adapter layer (CF Worker recommended)	2-3 days	WC REST API v3
Custom-built	Full implementation	5-8 days (all capabilities)	Own database and payment system
Magento	Adapter layer	3-4 days	Magento REST API
BigCommerce	Adapter layer	2-3 days	BC API v3

8.8 Multi-Merchant Hosting

When a platform hosts UCP for multiple merchants, several considerations apply: Profile routing: Each merchant should have its own subdomain or path prefix

https://store-a.platform.com/.well-known/ucp  -> Merchant A's Profile
https://store-b.platform.com/.well-known/ucp  -> Merchant B's Profile

Key isolation: Each merchant should have an independent signing key pair to prevent a key compromise from affecting all merchants. Capability customization: Different merchants may support different sets of capabilities (e.g., some merchants support returns, others do not). Each Profile should accurately reflect the individual merchant’s actual capabilities.

Next chapter: Testing and Validation — Profile validation, checkout flow testing, and security compliance checks

UCP merchant integration step-by-step guide UCP endpoint testing and compliance validation

Start

Learning Paths

Getting Started with AI Commerce

OTR Open Trust Registry

UCP Universal Commerce Protocol

ACP Agentic Commerce Protocol

MCP Model Context Protocol

SEO for the AI Era

ORBEXA Integrated Solution

Templates & Prompts

Glossary

UCP platform integration and multi-merchant hosting

Platform Integration Guide

8.1 The Role of Platforms

8.2 Implementing the Capability Negotiation Algorithm

Step 1: Compute the Intersection

Step 2: Select Versions

Step 3: Prune Orphaned Extensions

Step 4: Repeat Pruning Until Stable

8.3 Namespace Management

8.4 Shopify

8.5 WooCommerce

8.6 Custom-Built Stores

8.7 Platform Comparison

8.8 Multi-Merchant Hosting

​Platform Integration Guide

​8.1 The Role of Platforms

​8.2 Implementing the Capability Negotiation Algorithm

​Step 1: Compute the Intersection

​Step 2: Select Versions

​Step 3: Prune Orphaned Extensions

​Step 4: Repeat Pruning Until Stable

​8.3 Namespace Management

​8.4 Shopify

​8.5 WooCommerce

​8.6 Custom-Built Stores

​8.7 Platform Comparison

​8.8 Multi-Merchant Hosting

Platform Integration Guide

8.1 The Role of Platforms

8.2 Implementing the Capability Negotiation Algorithm

Step 1: Compute the Intersection

Step 2: Select Versions

Step 3: Prune Orphaned Extensions

Step 4: Repeat Pruning Until Stable

8.3 Namespace Management

8.4 Shopify

8.5 WooCommerce

8.6 Custom-Built Stores

8.7 Platform Comparison

8.8 Multi-Merchant Hosting