Composable Commerce and UCP: How AI Agents Navigate Headless Architectures

What Composable Commerce Is

Composable commerce is an approach to building e-commerce systems using independent, best-of-breed services connected through APIs. Instead of a monolithic platform that bundles everything, a composable stack combines discrete services: commercetools for commerce logic, Contentful for content, Algolia for search, and Stripe for payments. Each service does one thing well and exposes an API.

The term comes from the MACH Alliance: Microservices, API-first, Cloud-native, Headless. These four traits define what makes a commerce platform composable. The pattern has become the default architecture for enterprise retailers building for scale and flexibility.

The key trait for agents is the second one: API-first. Every interaction with a composable platform goes through an API. There is no special case for the browser. There is no scraping required. The API is the product.

Why Agents Prefer Headless Stacks

AI agents interact with commerce through code, not browsers. Traditional monolithic storefronts were designed for humans with screens. Composable stacks were designed for developers with API clients. The difference matters.

With a headless, API-first architecture:

• Product data is available through a documented REST or GraphQL endpoint
• Cart and checkout operations are programmable without browser automation
• Authentication is token-based with predictable response schemas
• Pagination, rate limits, and error codes are consistent and documented

An agent working against a headless commerce backend does not need to parse HTML, handle cookie-based sessions, or reverse-engineer JavaScript-rendered UIs. It calls the API, receives structured JSON, and proceeds.

A monolithic storefront forces agents to simulate human interactions. A composable stack invites programmatic ones.

How UCP Fits In

UCP (Universal Commerce Protocol) standardizes the interface layer across composable stacks. Without UCP, every composable stack is different even when the underlying architecture is similar. commercetools uses one authentication scheme; Shopify uses another. Cart APIs have different field names. Checkout flows have different steps. Agents that support multiple merchants need custom integrations for each one.

With UCP, a compliant composable stack exposes a standard endpoint. The agent authenticates once, reads the UCP manifest, and executes the same checkout flow regardless of whether the underlying stack uses commercetools, BigCommerce, or a custom-built API.

UCP does not replace the underlying stack. It adds a standard interface layer on top. The commerce platform handles business logic. UCP handles the protocol that agents use to interact with it. This is the key insight: composable stacks were already designed for programmatic access. UCP standardizes what that access looks like.

Contentful: Content Context for Agents

Contentful is the most common CMS in composable commerce stacks. It manages product descriptions, promotional terms, return policies, and editorial content that agents need to provide purchase context.

Agents query Contentful's Content Delivery API to retrieve structured product records:

const result = await fetch(
  cdaBase + '/entries?content_type=product&fields.slug=' + slug + '&include=2',
  { headers: { Authorization: 'Bearer ' + token } }
).then(r => r.json());

const product = result.items[0];
// product.fields.name, product.fields.price, product.fields.description

The response includes typed fields: name, description, price, related products, promotional badges. Agents use this content to populate product recommendations, explain purchase rationale, and verify that a product matches buyer criteria.

The CDN-backed CDA returns content in milliseconds. For agents operating in a conversational loop, fast content retrieval matters. Contentful's include depth parameter resolves linked entries in a single request, so agents do not need to chain multiple calls for related content.

commercetools: Commerce Logic for Agents

commercetools is the most API-mature commerce backend in the composable stack ecosystem. Its REST API covers product catalog, cart management, checkout, and order management with consistent authentication and response schemas.

Agents authenticate with OAuth 2.0 client credentials, then build and submit carts:

const auth = await fetch('https://auth.commercetools.com/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    scope: 'manage_orders:' + projectKey,
    client_id: process.env.CT_CLIENT_ID,
    client_secret: process.env.CT_CLIENT_SECRET,
  }),
}).then(r => r.json());

The cart API handles promotions, shipping, and tax automatically. Agents add items, set a shipping address, and call the checkout endpoint. They do not need to calculate totals or manage coupon logic. commercetools handles it.

This is the composable commerce value proposition for agents: the platform handles complexity (pricing rules, tax calculation, inventory checks) through the API. The agent does not need to replicate that logic.

Hygraph: Federated Data for Agents

Hygraph's content federation feature is particularly useful for agents operating in multi-source composable stacks. A single GraphQL endpoint can aggregate product data from commercetools, review data from a third-party service, and editorial content from Hygraph itself.

Agents query once and receive a complete product record:

query GetProduct($slug: String!) {
  product(where: { slug: $slug }) {
    name
    price
    description { text }
    categories { name }
    availableForSale
  }
}

No chaining multiple API calls. No joining data client-side. Hygraph handles the federation at query time. Agents receive the data shape they need for purchase decisions in a single request.

The typed GraphQL schema also means agents can introspect available fields without additional documentation. Schema introspection is a reliable way for agents to discover what data is queryable before writing a query.

The Pattern to Follow

Composable stacks with UCP integration follow a consistent agent workflow:

1. Discover the UCP business profile at /.well-known/ucp
2. Authenticate using the manifest-defined OAuth flow
3. Query the product catalog through the UCP catalog endpoint
4. Build a cart using UCP cart operations
5. Complete checkout through the UCP checkout endpoint
6. Track the order through the UCP order management endpoint

Each step uses standard UCP operations. The underlying stack (commercetools, Shopify, custom-built) is invisible to the agent. The agent integrates once against the UCP protocol and can transact with any compliant merchant.

The composable architecture makes implementing this pattern straightforward. Because each service in the stack already has a clean API, adding a UCP adapter layer is a matter of mapping operations, not rebuilding infrastructure.

Where Things Stand

Most composable commerce platforms are in the announced phase for UCP support. The technical prerequisites are already in place: API-first architectures, structured data models, OAuth authentication. Adding a UCP adapter layer is the remaining work.

Platforms that move first will be the ones agent developers prioritize. An agent that wants to buy from a commercetools-powered merchant today writes a custom integration. When that merchant publishes a UCP endpoint, the agent stops maintaining custom code and routes through the standard protocol.

Browse the Composable Commerce category in the UCPList directory for current integration status across Contentful, commercetools, Hygraph, and other platforms in this category.