Headless Commerce + UCP: The Developer Integration Guide

A headless commerce store has no built-in storefront. The commerce engine (catalog, cart, checkout, orders) is exposed entirely through APIs. A separate front end, often a React or Next.js app, calls those APIs to render the shopping experience. The commerce layer does not know or care what the front end looks like.

For AI agents, headless commerce is structurally favorable. There is no HTML to parse, no checkout form to fill, no UI interaction to simulate. The agent talks directly to the same API the front end uses. UCP formalizes this API surface.

This guide covers how UCP integrates with headless commerce stacks, what changes compared to monolithic platform integration, and how to write agents that work well with headless merchants.

Headless Architecture Recap

In a traditional ecommerce platform (Shopify Basic, WooCommerce, standard Magento), the commerce engine and the storefront are tightly coupled. Shopify renders the product page, cart, and checkout. The commerce data lives inside Shopify.

In a headless setup:

[Commerce Engine]  <-->  [API Layer]  <-->  [Custom Frontend]
  Elastic Path              REST/GraphQL       Next.js / React
  BigCommerce               Commerce APIs      Mobile app
  Commercetools             (not UCP)          Kiosk UI

UCP adds a standardized agent-facing API surface alongside the existing commerce APIs:

[Commerce Engine]  <-->  [API Layer]  <-->  [Custom Frontend]
  Elastic Path              REST/GraphQL       Next.js / React
  BigCommerce               Commerce APIs      Mobile app
  Commercetools
                   <-->  [UCP Endpoint]  <-->  [AI Agent]
                            /.well-known/ucp
                            /ucp/checkout

The UCP endpoint is a new API surface, but it draws from the same commerce engine data. Catalog, pricing, inventory, and order management all come from the same source of truth whether accessed through the custom front end or through the agent.

What Changes for Agents at Headless Merchants

Richer structured data

Headless merchants have already invested in structured product data because their frontend depends on it. A React frontend that renders product pages from an API requires clean, well-typed product data with consistent variant structures, pricing models, and attribute schemas.

Agents querying headless merchants through UCP benefit from this investment. You are less likely to encounter inconsistent product data, missing prices, or malformed variant structures. The same API discipline that makes headless frontends work makes agent integrations more reliable.

Direct API access, no scraping

Monolithic platforms sometimes require agents to parse storefront HTML when structured data is unavailable. Headless platforms have no storefront to parse. Every data point your agent needs is available through the API. UCP codifies the agent-facing subset of that API.

Flexible identity models

Headless merchants often have sophisticated customer identity systems built outside the commerce platform. An Elastic Path merchant might use Auth0 for identity and manage customer attributes in a separate CRM. A BigCommerce merchant might have a custom B2B portal with company accounts.

UCP identity linking at a headless merchant resolves the identity token against whatever identity system the merchant uses, not a platform-bundled customer account system. This is more flexible but also means the identity token capabilities vary more across headless merchants than across merchants on a single platform like Shopify.

Elastic Path: Composable Commerce APIs

Elastic Path exposes its commerce functions as separate API products: Catalog, Cart, Orders, Promotions, Accounts. A UCP integration maps these APIs to UCP capabilities:

// Elastic Path UCP capability mapping (illustrative, not live):
const ucpCapabilityMap = {
  // UCP capability -> Elastic Path API
  'catalog': 'https://api.elasticpath.com/pcm/catalog',
  'checkout': 'https://api.elasticpath.com/v2/carts',
  'orderManagement': 'https://api.elasticpath.com/v2/orders',
  'identityLinking': 'https://api.elasticpath.com/v2/accounts',
};

// Agent queries UCP manifest to discover checkout endpoint:
const manifest = await fetch('https://yourstore.com/.well-known/ucp').then(r => r.json());

// Checkout uses a single UCP endpoint, not individual Elastic Path APIs:
const session = await fetch(manifest.checkoutEndpoint, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-UCP-Payment-Token': paymentToken,
    'X-UCP-Identity-Token': identityToken,
  },
  body: JSON.stringify({ items: cartItems }),
}).then(r => r.json());

The UCP layer wraps Elastic Path's composable APIs into a single interaction for the agent. You do not need to know which Elastic Path products the merchant is using.

BigCommerce: API-First Platform

BigCommerce exposes its commerce layer through a Storefront API (GraphQL) and a Management API (REST). Headless BigCommerce merchants use these APIs to build custom storefronts. The UCP integration sits alongside these APIs.

// BigCommerce headless + UCP (illustrative, not live)

// Standard headless setup: custom frontend uses Storefront API
// Agent uses UCP endpoint (same commerce data, standardized interface)

// Discover merchant's UCP endpoint:
const manifest = await fetch('https://mystore.mybigcommerce.com/.well-known/ucp').then(r => r.json());
// or custom domain:
// const manifest = await fetch('https://www.yourbrand.com/.well-known/ucp').then(r => r.json());

// Catalog query through UCP (not BigCommerce Storefront API):
const products = await fetch(
  `${manifest.catalogEndpoint}?category=footwear&limit=20`
).then(r => r.json());

// Checkout through UCP:
const session = await fetch(manifest.checkoutEndpoint, {
  method: 'POST',
  body: JSON.stringify({
    items: [{ productId: products[0].id, variantId: products[0].defaultVariantId, quantity: 1 }],
    paymentToken: consumerPaymentToken,
  }),
}).then(r => r.json());

BigCommerce B2B Edition merchants expose customer group pricing through the identity-linking capability. An agent presenting a B2B identity token receives customer-group-adjusted prices, not list prices.

Commercetools: Pure API Commerce

Commercetools is a pure API commerce platform with no built-in storefront. Every interaction is through its REST and GraphQL APIs. The UCP integration for Commercetools maps its existing API surface to UCP's capability structure.

// Commercetools UCP integration pattern (illustrative)

// Commercetools merchant serves UCP manifest from their domain:
const manifest = await fetch('https://api.yourstore.com/.well-known/ucp').then(r => r.json());

// UCP catalog response uses Commercetools product projection data:
// {
//   items: [
//     {
//       id: 'ct-product-123',
//       name: 'Merino Wool Sweater',
//       variants: [
//         { id: 'v1', sku: 'MWS-M-NAVY', price: 12900, currency: 'USD', available: true },
//         { id: 'v2', sku: 'MWS-L-NAVY', price: 12900, currency: 'USD', available: false },
//       ]
//     }
//   ]
// }

// Checkout initiation through UCP endpoint:
const session = await fetch(manifest.checkoutEndpoint, {
  method: 'POST',
  body: JSON.stringify({
    items: [{ id: 'ct-product-123', variantId: 'v1', quantity: 2 }],
    paymentToken: ucpPaymentToken,
    shippingMethod: manifest.shippingMethods?.[0]?.id,
  }),
}).then(r => r.json());

Headless vs. Monolithic: What Your Agent Needs to Handle Differently

The main practical difference is variance. Shopify merchants have consistent data structures because Shopify defines the schema. Headless merchants have more variation because they configure their own product schemas.

Your agent should handle catalog response variance gracefully:

function extractPrice(item: UcpCatalogItem): number | null {
  // Handle different pricing structures across headless merchants
  if (typeof item.price === 'number') return item.price;
  if (item.price?.centAmount) return item.price.centAmount;
  if (item.variants?.[0]?.price) return item.variants[0].price;
  return null; // Log and skip items with unresolvable pricing
}

function extractSku(item: UcpCatalogItem): string | null {
  if (item.sku) return item.sku;
  if (item.variants?.[0]?.sku) return item.variants[0].sku;
  return item.id; // Fall back to platform ID if SKU absent
}

Testing Your Integration

Before targeting headless merchant endpoints in production:

1. Validate the manifest. Check that the manifest conforms to the UCP spec. Use the UCP Validator against each merchant endpoint.

1. Test catalog pagination. Headless merchants often have large catalogs. Verify that your agent handles paginated catalog responses without losing items or duplicating requests.

1. Test identity token rejection. If a headless merchant uses a custom identity provider, test what happens when your identity token is rejected. Do not assume identity linking will succeed.

1. Test inventory race conditions. Headless merchants with separate inventory systems may have lag between catalog availability data and actual inventory. Test checkout against items shown as available but actually out of stock.

1. Use the UCP Conformance Suite. The conformance suite has test cases for catalog, checkout, and identity linking. Run these against headless merchant endpoints to catch implementation gaps.

Where the Headless UCP Ecosystem Is Headed

Elastic Path, BigCommerce, and Commercetools have all announced UCP support. None are live at the time of writing. The implementations will differ because these platforms have different API architectures, but the UCP specification is the standard they are conforming to.

When these integrations go live, agents built to the UCP spec should work with minimal adaptation. The catalog query format, checkout request structure, and error codes will follow the spec. Merchant-specific variation will be in the product data schema and identity model, not in the UCP protocol layer.

Build to the spec now. Test against the conformance suite. When the headless platforms ship their UCP endpoints, you will be ready.