> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# UCP platform integration and multi-merchant hosting

> E-commerce platform UCP integration — capability negotiation, namespace management, multi-merchant hosting, and implementation paths.

# 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:

```javascript theme={null}
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):

```javascript theme={null}
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:

```javascript theme={null}
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

```javascript theme={null}
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:

```json theme={null}
{
  "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**:

```text theme={null}
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

| 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

```text theme={null}
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](/en/book-3/ch9-testing) — Profile validation, checkout flow testing, and security compliance checks