Adobe Merchant Services GraphQL

Adobe Merchant Services—Catalog Service, Live Search, and Product Recommendations—are SaaS extensions for Adobe Commerce that expose their own GraphQL schemas. These schemas are separate from the core Commerce GraphQL schema and optimized for fast, read-only storefront rendering.

How the three services relate to each other

Although each service addresses a distinct storefront use case, they share a common technical foundation and are designed to work together:

Shared dependency. Product Recommendations requires Catalog Service (v2.2.0 or later) to retrieve complete product data for each recommended item. If you use Product Recommendations, you must also have Catalog Service installed.

Complementary coverage. A typical storefront uses all three:

• products (Catalog Service) on the PDP
• productSearch (Live Search) on the PLP and search results page
• recommendations (Product Recommendations) as widgets on the PDP, home page, and cart page
• variants and refineProduct (Catalog Service) for option selection on the PDP

How Merchant Services differ from the core GraphQL schema

The core Commerce GraphQL endpoint (<commerce-url>/graphql) provides a comprehensive schema for all Commerce operations: catalog browsing, cart management, checkout, customer accounts, orders, and more. The Merchant Services schemas are narrowly scoped for read-only storefront rendering, and they differ from the core schema in the following ways.

Separate endpoints

Merchant Services queries do not use the standard Commerce GraphQL endpoint. They are sent to dedicated Adobe SaaS endpoints:

Different HTTP headers

Instead of the authentication tokens used by core Commerce, these services require SaaS context headers:

Different data types

Merchant Services return their own types that are not interchangeable with core types:

• The Catalog Service products query returns ProductView objects (SimpleProductView or ComplexProductView), not the core Products type. Prices, images, attributes, and options are structured differently.
• The Live Search productSearch query returns ProductSearchResponse with facets (Aggregation) and merchandising metadata. The core products query returns layered-navigation data for categories, which is a fundamentally different filtering model.
• Both the Catalog Service and core Commerce expose a categories query, but the Catalog Service version is read-optimized and returns only the data needed to render category navigation, not the full administrative category tree.

No write operations

Merchant Services schemas contain only queries. All mutations (cart, checkout, customer, orders) remain in the core schema and must be sent to the core endpoint.

When to use Merchant Services queries

Use Merchant Services queries when:

• Building or customizing a storefront and you need the fastest possible catalog rendering for PDPs, PLPs, search, or recommendations.
• Your storefront front end (for example, an Edge Delivery Services or headless storefront) needs to fetch catalog data independently from cart and checkout operations.
• You need advanced search features like semantic search, AI merchandising rules, synonyms, or faceted filtering that are not available in the core products query.
• You need AI-driven product recommendations that are automatically trained on shopper behavior.

Do not use Merchant Services queries when:

• You need to perform a write operation (add to cart, place an order, update a customer profile). These operations always use the core schema.
• You need real-time inventory or pricing that must be guaranteed up to the millisecond; Merchant Services data is indexed asynchronously.
• You are working on a server-side admin workflow or integration that reads data from Commerce for non-storefront purposes (use the core REST or GraphQL APIs instead).
• The Merchant Services extensions are not installed or your Commerce instance is not connected to Adobe's SaaS platform.

How Merchant Services differ from Adobe Commerce Optimizer

Adobe Commerce Optimizer is a standalone SaaS platform that is not installed as an extension on an existing Commerce instance. It provides the Merchandising GraphQL API, which covers a similar set of storefront use cases but with a different architecture, different query signatures, and different headers.

Architectural difference

Different headers

Commerce Optimizer uses a different set of context headers that reflect its catalog-view model:

Query-level differences

The Merchandising GraphQL API provides queries that are similar in name to some Merchant Services queries but are not identical in structure or behavior:

When to use Commerce Optimizer instead

Use the Commerce Optimizer Merchandising GraphQL API instead of Merchant Services queries when:

• You are building on Adobe Commerce Optimizer as a standalone SaaS platform rather than on an Adobe Commerce (PaaS/SaaS) instance.
• Your storefront needs to serve multiple catalog views or channel-specific product catalogs controlled by Commerce Optimizer policies.
• You are migrating off a traditional Commerce installation and Commerce Optimizer is the designated catalog backend.

If you are running Adobe Commerce (PaaS or SaaS) with the Merchant Services extensions installed, use the Merchant Services queries described in this section. The two API surfaces are not interchangeable—switching endpoints without also migrating your catalog data and context configuration will result in errors.

Combining schemas with API Mesh

Because Merchant Services and Commerce Optimizer both use separate endpoints from the core Commerce GraphQL endpoint, a storefront often needs to make requests to multiple endpoints. You can use API Mesh for Adobe Developer App Builder to unify multiple GraphQL schemas—including the core Commerce schema, Catalog Service, Live Search, and third-party APIs—into a single endpoint. API Mesh also handles the context headers for each upstream service automatically, simplifying storefront development.

Last updated 3/23/2026

Was this helpful?

Yes

No