Skip to main content

​
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:
  1. Ensure product data is complete (title, description, price, inventory, images, SKU)
  2. Enable the Storefront API
  3. Deploy a /.well-known/ucp Profile (via a Shopify App or custom proxy)
  4. 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:
  1. Deploy the /.well-known/ucp Profile (refer to Section 7.2)
  2. Implement the product catalog API (REST and/or MCP transport)
  3. Implement the checkout state machine (6 states, 5 operations)
  4. Generate ES256 signing keys and configure Webhooks
  5. Implement OAuth 2.0 and order management as needed

​
8.7 Platform Comparison

PlatformIntegration PathEstimated EffortKey Dependency
ShopifyWait for official plugin or build a proxy0.5-1 day (proxy)Storefront API
WooCommerceAdapter layer (CF Worker recommended)2-3 daysWC REST API v3
Custom-builtFull implementation5-8 days (all capabilities)Own database and payment system
MagentoAdapter layer3-4 daysMagento REST API
BigCommerceAdapter layer2-3 daysBC 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