UCP for commercetools: Developer Integration Guide

commercetools and UCP

commercetools is the dominant composable commerce platform for enterprise retailers. Its API-first architecture makes it well-suited for UCP: the product, pricing, inventory, and order APIs that UCP needs already exist. The work is wiring them together through the UCP Connect module rather than building from scratch.

This guide covers the complete UCP integration path for a commercetools project. By the end, you will have a live /.well-known/ucp manifest, a working catalog endpoint, and a checkout flow tested with the UCP conformance suite.

Before You Start

You need a commercetools project with:

• Composable Commerce APIs (Products, Categories, Prices, Inventory, Carts, Orders)
• A configured payment integration (Stripe, Adyen, or Braintree recommended)
• Access to the commercetools Connect marketplace
• An SSL-enabled storefront domain

If you are on the commercetools Merchant Center, navigate to Settings > Connect to access the marketplace. The UCP Connector is listed there.

Step 1: Install the UCP Connect Module

From the commercetools Connect marketplace, search for "UCP Connector" and install it into your project. The connector requires the following OAuth scopes on your API client:

manage_products:{projectKey}
view_products:{projectKey}
manage_orders:{projectKey}
manage_customers:{projectKey}
manage_payments:{projectKey}

Create a new API client with these scopes if your existing client does not have them. Avoid reusing a superadmin client for UCP; scope it to what UCP actually needs.

Step 2: Configure the Manifest

After installation, the connector UI presents a manifest configuration form. Fill in the following:

Store identifier. This is the string agents use to identify your store in multi-merchant queries. Use your brand name in lowercase with hyphens. It must be unique on the UCP network.

Product projection. Choose the published product projection. Staged projections expose draft products that may not be available for purchase. UCP catalog queries should always hit published data.

Price channel and customer group. If you use channel-specific or customer-group-specific pricing, select the channel and group that represents your default consumer prices. For B2B projects, this step is handled separately in the identity linking configuration.

Payment handlers. The connector lists detected payment integrations from your commercetools project. Map each payment provider to its UCP handler identifier: Stripe is com.stripe, Adyen is com.adyen, Braintree is com.braintree.

Save the configuration. The connector immediately starts serving /.well-known/ucp at your configured domain.

Verify the manifest:

curl https://yourstore.com/.well-known/ucp | jq .

You should see a JSON manifest with your store name, capability list, and endpoint URLs.

Step 3: Catalog Endpoint Mapping

The connector maps commercetools Product Projections to UCP catalog payloads. The default mapping covers:

• name -> product.title
• description -> product.description
• masterVariant.prices[0].value -> product.price
• masterVariant.availability.availableQuantity -> product.inventoryCount
• masterVariant.images[0].url -> product.imageUrl

For products with variants (size, color, material), each variant becomes a separate UCP product entry with a variant reference back to the parent. This is the standard UCP pattern for variant-heavy catalogs.

If your products use custom attributes, map them in the connector's attribute mapping panel. Custom attributes flow through to the UCP catalog as product.attributes, where agents can use them in structured queries.

Step 4: B2B Identity Linking

commercetools projects serving B2B merchants have customer groups with contract pricing. UCP Identity Linking allows authenticated B2B buyers to carry their customer group assignment into agent-initiated sessions.

Configure B2B identity linking in the connector:

1. Set the identity provider to your existing B2B SSO (Okta, Azure AD, or a custom provider)
2. Map the identity provider's group claim to commercetools customer groups
3. Set the price selection rule to use the customer group from the identity token

When a B2B agent initiates checkout with a valid identity token, the connector resolves the customer group and applies contract pricing automatically. The agent receives the negotiated price in the catalog response without any additional API calls.

// B2B agent checkout with identity token
const session = await fetch('https://yourstore.com/ucp/checkout', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-UCP-Identity-Token': identityToken, // pre-authorized by the agent platform
  },
  body: JSON.stringify({
    productId: 'abc123',
    quantity: 100,
    paymentHandler: 'com.stripe',
  }),
}).then(r => r.json());

console.log(session.price); // contract price, not list price

Step 5: Run Conformance

Install and run the UCP conformance suite against your endpoint:

git clone https://github.com/universal-commerce-protocol/conformance
cd conformance
npm install
npm test -- --endpoint https://yourstore.com/.well-known/ucp

The suite runs tests across all declared capabilities. Common failures for commercetools integrations:

Inventory race condition. The catalog query returns available stock, but by checkout time the item is gone. The connector handles this by re-checking inventory at checkout initiation and returning a 409 Conflict if stock dropped to zero. Make sure your agent handles the 409 and retries with an alternative product.

Price currency mismatch. Agents may request prices in a currency your commercetools project supports but the connector does not have a channel configured for. Add a catch-all price channel in the connector settings for currencies you want to serve.

Missing required fields. If your product catalog has items without prices or without inventory data, those items are excluded from UCP catalog responses. Review the connector's exclusion log in the Merchant Center.

What to Watch After Launch

Monitor the connector's request log for the first 48 hours after going live. The log shows every agent query, what products were returned, and whether checkout sessions were initiated. High catalog query rates with zero checkout initiations usually means your pricing or checkout flow has an issue agents cannot work around.

The commercetools Merchant Center dashboard shows UCP-sourced orders tagged with the agent identifier in the order metadata. Track the share of orders arriving through UCP vs. direct channels. For enterprise merchants with AI-heavy customer bases, this number grows quickly.

Once you are live on UCPList at ucplist.ai, filter by platform to see which other commercetools merchants are on UCP. That community is a useful resource for connector configuration questions.