Introduction

The Universal Commerce Protocol (UCP) integration exposes the non-transactional catalog capabilities of Intershop Commerce Management (ICM) through the open UCP standard. The integration is a standalone, read-only adapter service. AI shopping and procurement agents that already know the shop's address read its machine-readable UCP profile, then send UCP Search and Lookup requests. The service translates these requests into calls to the existing ICM REST API and maps the results to the UCP product model. It does not implement cart, checkout, payment, or order flows.

References

• Feature List - Universal Commerce Protocol (EN)

• Universal Commerce Protocol

• GitHub | UCP | Release v2026-08-25

Feature Overview

For the full capability list, see Feature List - Universal Commerce Protocol (EN).

• • UCP business profile under /.well-known/ucp with schema and specification links

  • OpenAPI documentation for the Search and Lookup endpoints

  • Catalog Search through the ICM REST API, with a category filter, a price filter, and cursor pagination

  • Catalog Lookup by identifier, single and batch

  • Product detail with all variants and options, plus variant narrowing by selected option values (data only, see Variant Selection)

  • Support for simple products, variation masters, variations, product bundles, and retail sets

  • Prices and price ranges as integer minor units with an ISO 4217 currency code

  • Language and currency selection per request from a configured, advertised set (no currency conversion)

  • Deep links to the storefront product page for each product

  • Optional multi-channel operation from a single instance, resolved by Host

  • Elastic Common Schema (ECS)-compatible JSON logging

Flow and Architecture

End-to-End Flow

1. The agent knows the shop's address. The address reaches the agent out of band: a user enters it, an operator configures it, or the agent finds it in a link or directory. UCP does not define how agents find shops.

2. The agent reads the profile. It calls GET https://<shop-host>/.well-known/ucp. The profile states the UCP version, the transport (rest), the endpoint base URL (/ucp/v1), a link to the OpenAPI document, the supported languages and currencies, and the declared capabilities (dev.ucp.shopping.catalog.search and dev.ucp.shopping.catalog.lookup).

3. The agent checks compatibility. It compares the UCP version and the capabilities with what it supports. Optionally, it reads /ucp/v1/openapi.json and the linked UCP schemas on ucp.dev.

4. The agent runs Search or Lookup.

   • Search: POST /ucp/v1/catalog/search with a free-text query, optional filters, and a cursor.

   • Lookup: POST /ucp/v1/catalog/lookup with up to 100 product identifiers.

   • Product detail: POST /ucp/v1/catalog/product with one identifier and optional selected option values.

   • Optional headers Accept-Language and Accept-Currency select the language and currency.

5. The service queries ICM. It resolves the ICM channel from the request Host, negotiates language and currency, and calls the ICM REST API. A search returns product references from ICM. The service then loads each product, and its variation master if applicable, from ICM.

6. The service maps and returns. It converts ICM products to UCP products and variants, prices to integer minor units, and adds storefront deep links. It returns the UCP response envelope with products, pagination, and informational messages, such as unknown identifiers.

7. The agent processes the response. It presents results to the user, pages further, or requests details. To buy, the user follows the product's storefront link. Transactions are out of scope.

Sequence Diagram

Architecture

The following figure shows the architecture of the Universal Commerce Protocol (UCP) and its main components.

The service holds no state and stores no data. It scales horizontally.

Discovery

The profile under /.well-known/ucp describes what a known origin offers: the supported UCP capabilities, the endpoint, and the available languages and currencies. Discovery in the UCP sense means "capability discovery for a given shop", not "product discovery on AI platforms".

Publishing the profile does not make products findable in ChatGPT, Gemini, or other AI assistants. These platforms use their own merchant onboarding and product feed programs. For example, Google AI Mode and Gemini rely on Google Merchant Center feeds. Such feeds and platform registrations are not part of this integration. The integration serves agents that are directed to the shop and call the UCP catalog endpoints directly.

Authentication and Data Visibility

Version 0.1 handles authentication as follows:

Consequence: A channel that hides its catalog or prices from anonymous users returns no data or incomplete data through UCP. Use a channel with a public catalog.

Price Filter and Paging

The ICM product search has no parameter for arbitrary price bounds. The service therefore works as follows:

1. It fetches one page of hits from ICM (pagination.limit, default 10, maximum 50).

2. It maps the hits and removes products whose price range lies completely outside filters.price. Products without a price are kept.

3. It returns the remaining products together with the cursor of the unfiltered ICM page.

Consequences:

• A page can contain fewer products than limit, or none at all, even though later pages contain matching products.

• An empty products array with has_next_page: true does not mean "no results". The agent must continue with pagination.cursor until has_next_page is false.

• total_count is the number of ICM hits for the query and category, not the number of products within the price range.

• Price bounds are integer minor units in the response currency (for example 10000 for 100.00 €). There is no conversion between currencies.

Example "show products under 100 €": the agent sends "filters": {"price": {"max": 10000}} with Accept-Currency: EUR. For the demo, combine it with a category filter (pushed down to ICM) and "pagination": {"limit": 50} to reduce the number of empty or sparse pages. The playground's Load more button follows the cursor in the same way.

Variant Selection

The service delivers data for variant selection. It does not provide a user interface. The interaction is implemented by the consuming agent or client.

What the service returns:

• Search and Lookup: One featured, purchasable variant per product, plus a price_range across all variants of the master. Lookup returns the variant that matches the requested identifier.

• Product detail (POST /ucp/v1/catalog/product):

  • All variants, each with its SKU, price, availability, and option values (for example, Size: 10).

  • The product-level options list with all values. Each value carries exists (a variant with this value exists for the current selection) and available (such a variant is in stock).

  • selected with the option values of the currently featured variant.

What the agent or client does:

1. Show the options and values to the user, using exists and available to disable or mark values.

2. On a user choice, call POST /ucp/v1/catalog/product again with "selected": [{"name": "...", "label": "..."}].

3. Optionally send "preferences": ["<most important option>", ...]. If no variant matches all selected values, the service drops the least important option first and returns the closest existing variant.

4. Use the returned variant's SKU and storefront link for the next step.

The playground at /ucp/playground demonstrates this flow for developers. It is disabled by default and is not part of the product interface.

Language and Currency

• The operator configures the supported languages (ICM_SUPPORTED_LOCALES) and currencies (ICM_SUPPORTED_CURRENCIES) per deployment or per market. The profile advertises them as supported_locales and supported_currencies.

• The agent selects a value per request with Accept-Language and Accept-Currency. Only advertised values are accepted. This is a selection from a fixed set, not a free choice.

• Unsupported values do not cause an error. The service silently falls back to the channel default. The selected language is returned in the Content-Language header. The actual currency is visible in the currency field of every price. Agents should check it.

• No currency conversion. The service passes the currency to ICM and returns the prices that ICM has maintained for that currency. If ICM has no price in that currency, products can be returned without a price.

• An ICM channel typically uses one currency. Advertise only currencies for which the channel has prices, or configure one market per channel and currency with UCP_MARKETS.

Limitations

The integration implements a limited, non-transactional subset of UCP. The following capabilities are out of scope by design:

• All transactional flows: cart, checkout, payment, order placement, and order management

• Returns, refunds, and dispute flows

• Identity linking and transaction authorization artifacts (signing, idempotency, audit, payment guarantees)

• Customer-specific prices, price lists, and catalogs (see Authentication and Data Visibility)

• Registration with AI platforms and product feeds such as Google Merchant Center (see Discovery)

Additional constraints:

• The service is read-only. It maps ICM data to the UCP model and leaves ICM data unchanged.

• Inbound access control and rate limiting are not part of the service and must be configured at the ingress if required.

• Search sends only the first category filter to ICM.

• The price filter applies to each returned page only. Pages can be sparse or empty, and total_count ignores the price filter (see Price Filter and Paging).

• There is no currency conversion. Unsupported languages and currencies fall back to the channel default (see Language and Currency).