From 39eec5b2e5fdda8600fed139ce11fa4b11da63d1 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Wed, 18 Mar 2026 15:08:26 -0500 Subject: [PATCH 1/8] Create merchant services schema section --- src/data/navigation/sections/graphql.js | 74 +++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/src/data/navigation/sections/graphql.js b/src/data/navigation/sections/graphql.js index be46c34cc..03cae9c96 100644 --- a/src/data/navigation/sections/graphql.js +++ b/src/data/navigation/sections/graphql.js @@ -1361,6 +1361,80 @@ module.exports = [ }, ], }, + { + title: "Merchant Services Schema", + path: "/graphql/schema/merchant-services/", + pages: [ + { + title: "Catalog Service", + path: "/graphql/schema/catalog-service/", + pages:[ + { + title: "Queries", + path: "/graphql/schema/catalog-service/queries/", + pages: [ + { + title: "categories", + path: "/graphql/schema/catalog-service/queries/categories.md", + }, + { + title: "products", + path: "/graphql/schema/catalog-service/queries/products.md" + }, + { + title: "productSearch", + path: "/graphql/schema/live-search/queries/product-search.md", + }, + { + title: "refineProduct", + path: "/graphql/schema/catalog-service/queries/refine-product.md" + }, + { + title: "variants", + path: "/graphql/schema/catalog-service/queries/product-variants.md" + } + ], + }, + ], + }, + { + title: "Live Search", + path: "/graphql/schema/live-search", + pages: [ + { + title: "Queries", + path: "/graphql/schema/live-search/queries/", + pages: [ + { + title: "attributeMetadata", + path: "/graphql/schema/live-search/queries/attribute-metadata/", + }, + { + title: "productSearch", + path: "/graphql/schema/live-search/queries/product-search/", + } + ], + } + ] + }, + { + title: "Product Recommendations", + path: "/graphql/schema/product-recommendations/", + pages: [ + { + title: "Queries", + path: "/graphql/schema/product-recommendations/queries/", + pages: [ + { + title: "recommendations", + path: "/graphql/schema/product-recommendations/queries/recommendations/", + } + ] + }, + ] + } + ] + }, { title: "Core payment methods", path: "/graphql/payment-methods/", From 6a5ce81bfad8bdf7241376853bfe4cbc1456c586 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Mon, 23 Mar 2026 14:51:59 -0500 Subject: [PATCH 2/8] Group Merchant Services queries together --- src/data/navigation/sections/graphql.js | 68 --------- .../graphql/schema/merchant-services/index.md | 142 ++++++++++++++++++ 2 files changed, 142 insertions(+), 68 deletions(-) create mode 100644 src/pages/graphql/schema/merchant-services/index.md diff --git a/src/data/navigation/sections/graphql.js b/src/data/navigation/sections/graphql.js index 03cae9c96..2d0b16ee2 100644 --- a/src/data/navigation/sections/graphql.js +++ b/src/data/navigation/sections/graphql.js @@ -323,38 +323,6 @@ module.exports = [ }, ], }, - { - title: "Catalog Service", - path: "/graphql/schema/catalog-service/", - pages:[ - { - title: "Queries", - path: "/graphql/schema/catalog-service/queries/", - pages: [ - { - title: "categories", - path: "/graphql/schema/catalog-service/queries/categories.md", - }, - { - title: "products", - path: "/graphql/schema/catalog-service/queries/products.md" - }, - { - title: "productSearch", - path: "/graphql/schema/live-search/queries/product-search.md", - }, - { - title: "refineProduct", - path: "/graphql/schema/catalog-service/queries/refine-product.md" - }, - { - title: "variants", - path: "/graphql/schema/catalog-service/queries/product-variants.md" - } - ], - }, - ], - }, { title: "Checkout", path: "/graphql/schema/checkout/", @@ -729,26 +697,6 @@ module.exports = [ }, ], }, - { - title: "Live Search", - path: "/graphql/schema/live-search", - pages: [ - { - title: "Queries", - path: "/graphql/schema/live-search/queries/", - pages: [ - { - title: "attributeMetadata", - path: "/graphql/schema/live-search/queries/attribute-metadata/", - }, - { - title: "productSearch", - path: "/graphql/schema/live-search/queries/product-search/", - } - ], - } - ] - }, { title: "Negotiable quotes (B2B)", path: "/graphql/schema/b2b/negotiable-quote/", @@ -927,22 +875,6 @@ module.exports = [ } ], }, - { - title: "Product Recommendations", - path: "/graphql/schema/product-recommendations/", - pages: [ - { - title: "Queries", - path: "/graphql/schema/product-recommendations/queries/", - pages: [ - { - title: "recommendations", - path: "/graphql/schema/product-recommendations/queries/recommendations/", - } - ] - }, - ] - }, { title: "Products", path: "/graphql/schema/products/", diff --git a/src/pages/graphql/schema/merchant-services/index.md b/src/pages/graphql/schema/merchant-services/index.md new file mode 100644 index 000000000..dfc7f099c --- /dev/null +++ b/src/pages/graphql/schema/merchant-services/index.md @@ -0,0 +1,142 @@ +--- +title: Adobe Merchant Services GraphQL +description: Learn how Catalog Service, Live Search, and Product Recommendations GraphQL queries relate to each other and to the core Commerce schema. +keywords: + - GraphQL + - Services + - Catalog Service + - Live Search + - Product Recommendations +--- + +# Adobe Merchant Services GraphQL + +Adobe Merchant Services—[Catalog Service](../catalog-service/), [Live Search](../live-search/), and [Product Recommendations](../product-recommendations/)—are SaaS extensions for Adobe Commerce that expose their own GraphQL schemas. These schemas are separate from the [core Commerce GraphQL schema](../index.md) 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: + +| Service | Primary purpose | +| --- | --- | +| **Catalog Service** | Renders product detail pages (PDPs) and product compare pages by fetching rich product data by SKU. | +| **Live Search** | Powers product listing pages (PLPs) and on-site search with AI-driven relevance, faceting, and merchandising rules. | +| **Product Recommendations** | Surfaces AI-generated product suggestions ("Customers who viewed this also viewed…") as recommendation units on any storefront page. | + +**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 (`/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: + +| Edition | Environment | Endpoint | +| --- | --- | --- | +| PaaS | Testing | `https://catalog-service-sandbox.adobe.io/graphql` | +| PaaS | Production | `https://catalog-service.adobe.io/graphql` | +| SaaS | Testing | `https://na1-sandbox.api.commerce.adobe.com/{{tenant-id}}/graphql` | +| SaaS | Production | `https://na1.api.commerce.adobe.com/{{tenant-id}}/graphql` | + +### Different HTTP headers + +Instead of the authentication tokens used by core Commerce, these services require SaaS context headers: + +| Header | Required by | Description | +| --- | --- | --- | +| `Magento-Environment-Id` | All three services | The SaaS Data Space ID from the Commerce Admin | +| `Magento-Store-Code` | All three services | Store code | +| `Magento-Store-View-Code` | All three services | Store view code | +| `Magento-Website-Code` | All three services | Website code | +| `X-Api-Key` | Catalog Service, Product Recommendations | Unique API key for your Commerce environment | +| `X-Api-Key: search_gql` | Live Search | Fixed value required for Live Search requests | +| `Magento-Customer-Group` | Catalog Service, Product Recommendations | Customer group for personalized pricing | + +### 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 + +| Aspect | Merchant Services | Commerce Optimizer | +| --- | --- | --- | +| **Deployment model** | Extensions installed on an existing Adobe Commerce (PaaS or SaaS) instance | Standalone SaaS platform; catalog data is ingested via a separate Data Ingestion API | +| **Data source** | Commerce catalog, indexed into Adobe SaaS | Data ingested independently into Commerce Optimizer | +| **Context model** | Store view and website codes from Commerce | Catalog views and policies defined in Commerce Optimizer | +| **Authentication** | `X-Api-Key` tied to your Commerce environment | No API key required; context is provided through `AC-View-Id` | + +### Different headers + +Commerce Optimizer uses a different set of context headers that reflect its catalog-view model: + +| Header | Description | +| --- | --- | +| `AC-View-Id` | Required. Identifies the catalog view (replaces `Magento-Store-View-Code` / `Magento-Environment-Id`) | +| `AC-Price-Book-ID` | Optional. Specifies the price book for pricing context | +| `AC-Policy-{*}` | Optional. Restricts product access based on request attributes (for example, brand or channel policies) | + +### 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: + +| Query | Merchant Services | Commerce Optimizer | +| --- | --- | --- | +| `products` | Catalog Service — fetch by SKU, returns `ProductView` | Same name, same general purpose, but uses `AC-View-Id` context | +| `productSearch` | Live Search / Catalog Service — full search with `phrase`, `filter`, `sort`, optional `context` | Similar structure, but context is provided through headers rather than a `context` input object | +| `attributeMetadata` | Live Search — returns filterable and sortable attributes | Same name and purpose; independent implementation | +| `refineProduct` | Catalog Service — narrow complex product options by selection | Equivalent query available | +| `variants` | Catalog Service — return all variant combinations | Equivalent query available | +| `categories` | Catalog Service — return category hierarchy | Commerce Optimizer uses `categoryTree` with `family` and `slugs` arguments | +| `recommendations` | Product Recommendations — returns units by recommendation type | Commerce Optimizer uses `recommendationsByUnitIds`, which requires pre-configured unit IDs | +| _(none)_ | Not available in Merchant Services | `navigation` — returns category-based navigation structure | + +### 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](https://developer.adobe.com/graphql-mesh-gateway/) 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. From f96c52ada48e2b769dd7be20e34933ce75771795 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Thu, 2 Apr 2026 09:54:05 -0500 Subject: [PATCH 3/8] Apply suggestions from code review Co-authored-by: Margaret Eker --- src/data/navigation/sections/graphql.js | 2 +- .../graphql/schema/merchant-services/index.md | 50 +++++++++---------- 2 files changed, 26 insertions(+), 26 deletions(-) diff --git a/src/data/navigation/sections/graphql.js b/src/data/navigation/sections/graphql.js index 676d0b682..10ada9fc7 100644 --- a/src/data/navigation/sections/graphql.js +++ b/src/data/navigation/sections/graphql.js @@ -1326,7 +1326,7 @@ module.exports = [ ], }, { - title: "Merchant Services Schema", + title: "Storefront Services Schema", path: "/graphql/schema/merchant-services/", pages: [ { diff --git a/src/pages/graphql/schema/merchant-services/index.md b/src/pages/graphql/schema/merchant-services/index.md index dfc7f099c..fcee436d9 100644 --- a/src/pages/graphql/schema/merchant-services/index.md +++ b/src/pages/graphql/schema/merchant-services/index.md @@ -1,5 +1,5 @@ --- -title: Adobe Merchant Services GraphQL +title: Adobe Storefront Services GraphQL description: Learn how Catalog Service, Live Search, and Product Recommendations GraphQL queries relate to each other and to the core Commerce schema. keywords: - GraphQL @@ -9,9 +9,9 @@ keywords: - Product Recommendations --- -# Adobe Merchant Services GraphQL +# Adobe Storefront Services GraphQL -Adobe Merchant Services—[Catalog Service](../catalog-service/), [Live Search](../live-search/), and [Product Recommendations](../product-recommendations/)—are SaaS extensions for Adobe Commerce that expose their own GraphQL schemas. These schemas are separate from the [core Commerce GraphQL schema](../index.md) and optimized for fast, read-only storefront rendering. +Adobe Storefront Services—[Catalog Service](../catalog-service/), [Live Search](../live-search/), and [Product Recommendations](../product-recommendations/)—are SaaS extensions for Adobe Commerce that expose their own GraphQL schemas. These schemas are separate from the [core Commerce GraphQL schema](../index.md) and optimized for fast, read-only storefront rendering. ## How the three services relate to each other @@ -23,7 +23,7 @@ Although each service addresses a distinct storefront use case, they share a com | **Live Search** | Powers product listing pages (PLPs) and on-site search with AI-driven relevance, faceting, and merchandising rules. | | **Product Recommendations** | Surfaces AI-generated product suggestions ("Customers who viewed this also viewed…") as recommendation units on any storefront page. | -**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. +**Shared dependency.** Both Live Search and Product Recommendations require Catalog Service (v2.2.0 or later) to retrieve complete product data for each recommended item. If you are using Live Search 3.0.2 or later and Product Recommendations 3.0.2 or later, the Catalog Service is installed automatically when you install or update the extensions. **Complementary coverage.** A typical storefront uses all three: @@ -32,13 +32,13 @@ Although each service addresses a distinct storefront use case, they share a com - `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 +## How Storefront Services differ from the core GraphQL schema -The core Commerce GraphQL endpoint (`/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. +The core Commerce GraphQL endpoint (`/graphql`) provides a comprehensive schema for all Commerce operations: catalog browsing, cart management, checkout, customer accounts, orders, and more. The Storefront 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: +Storefront Services queries do **not** use the standard Commerce GraphQL endpoint. They are sent to dedicated Adobe SaaS endpoints: | Edition | Environment | Endpoint | | --- | --- | --- | @@ -49,7 +49,7 @@ Merchant Services queries do **not** use the standard Commerce GraphQL endpoint. ### Different HTTP headers -Instead of the authentication tokens used by core Commerce, these services require SaaS context headers: +These services use SaaS context headers instead of the authentication tokens used by core Commerce. | Header | Required by | Description | | --- | --- | --- | @@ -63,7 +63,7 @@ Instead of the authentication tokens used by core Commerce, these services requi ### Different data types -Merchant Services return their own types that are not interchangeable with core types: +Storefront 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. @@ -71,34 +71,34 @@ Merchant Services return their own types that are not interchangeable with core ### 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. +Storefront Services schemas contain only queries. All mutations (cart, checkout, customer, orders) are in the core schema and must be sent to the core endpoint. -## When to use Merchant Services queries +## When to use Storefront Services queries -**Use Merchant Services queries when:** +**Use Storefront 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. +- Building or customizing a storefront that requires the fastest possible catalog rendering for PDPs, PLPs, search, or recommendations. +- Your storefront frontend (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:** +**Do not use Storefront 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). +- You need real-time inventory or pricing that must be guaranteed up to the millisecond; Storefront 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. In this case, 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 +## How Storefront 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 -| Aspect | Merchant Services | Commerce Optimizer | +| Aspect | Storefront Services | Commerce Optimizer | | --- | --- | --- | | **Deployment model** | Extensions installed on an existing Adobe Commerce (PaaS or SaaS) instance | Standalone SaaS platform; catalog data is ingested via a separate Data Ingestion API | -| **Data source** | Commerce catalog, indexed into Adobe SaaS | Data ingested independently into Commerce Optimizer | +| **Data source** | Commerce catalog, indexed into the Adobe SaaS data space | Data ingested independently into the Commerce Optimizer instance | | **Context model** | Store view and website codes from Commerce | Catalog views and policies defined in Commerce Optimizer | | **Authentication** | `X-Api-Key` tied to your Commerce environment | No API key required; context is provided through `AC-View-Id` | @@ -127,16 +127,16 @@ The Merchandising GraphQL API provides queries that are similar in name to some | `recommendations` | Product Recommendations — returns units by recommendation type | Commerce Optimizer uses `recommendationsByUnitIds`, which requires pre-configured unit IDs | | _(none)_ | Not available in Merchant Services | `navigation` — returns category-based navigation structure | -### When to use Commerce Optimizer instead +### When to use Commerce Optimizer -Use the Commerce Optimizer Merchandising GraphQL API instead of Merchant Services queries when: +Use the Commerce Optimizer Merchandising GraphQL API instead of Storefront Services queries when: -- You are building on Adobe Commerce Optimizer as a standalone SaaS platform rather than on an Adobe Commerce (PaaS/SaaS) instance. +- 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. +If you are running Adobe Commerce (PaaS or SaaS) with the Storefront Services extensions installed, use the Storefront 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](https://developer.adobe.com/graphql-mesh-gateway/) 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. +Because Storefront 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](https://developer.adobe.com/graphql-mesh-gateway/) 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. From e18d583a4a8c2cd9aaa7dbb555e03e90281d55d8 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Thu, 2 Apr 2026 16:26:19 -0500 Subject: [PATCH 4/8] Review comments --- src/_includes/graphql/endpoints.md | 14 +++++--------- src/data/navigation/sections/graphql.js | 2 +- .../index.md | 17 ++++++++++------- 3 files changed, 16 insertions(+), 17 deletions(-) rename src/pages/graphql/schema/{merchant-services => storefront-services}/index.md (86%) diff --git a/src/_includes/graphql/endpoints.md b/src/_includes/graphql/endpoints.md index a327910ff..10c761d01 100644 --- a/src/_includes/graphql/endpoints.md +++ b/src/_includes/graphql/endpoints.md @@ -9,15 +9,11 @@ | Environment | Endpoint | | ------------ | --------:| -| Testing | `https://na1-sandbox.api.commerce.adobe.com/{{tenant-id}}/graphql` | -| Production (Not available yet) | `https://na1.api.commerce.adobe.com/{{tenant-id}}/graphql` | +| Testing | `https://{{region}}-{{environment}}.api.commerce.adobe.com/{{tenant-id}}/graphql` | +| Production | `https://{{region}}.api.commerce.adobe.com/{{tenant-id}}/graphql` | **URL structure for SaaS endpoints** -```text -https://-.api.commerce.adobe.com//graphql -``` - -- `` is the cloud region where your instance is deployed. -- `` is the environment type, such as `sandbox`. If the environment is production, this value is omitted. -- `` is the unique identifier for your organization's specific instance within the Adobe Experience Cloud. +- `region` is the cloud region where your instance is deployed. +- `environment` is the environment type, such as `sandbox`. If the environment is production, this value is omitted. +- `tenantId` is the unique identifier for your organization's specific instance within the Adobe Experience Cloud. diff --git a/src/data/navigation/sections/graphql.js b/src/data/navigation/sections/graphql.js index 75511184a..6bdd7106c 100644 --- a/src/data/navigation/sections/graphql.js +++ b/src/data/navigation/sections/graphql.js @@ -1331,7 +1331,7 @@ module.exports = [ }, { title: "Storefront Services Schema", - path: "/graphql/schema/merchant-services/", + path: "/graphql/schema/storefront-services/", pages: [ { title: "Catalog Service", diff --git a/src/pages/graphql/schema/merchant-services/index.md b/src/pages/graphql/schema/storefront-services/index.md similarity index 86% rename from src/pages/graphql/schema/merchant-services/index.md rename to src/pages/graphql/schema/storefront-services/index.md index fcee436d9..3385b5d65 100644 --- a/src/pages/graphql/schema/merchant-services/index.md +++ b/src/pages/graphql/schema/storefront-services/index.md @@ -13,6 +13,8 @@ keywords: Adobe Storefront Services—[Catalog Service](../catalog-service/), [Live Search](../live-search/), and [Product Recommendations](../product-recommendations/)—are SaaS extensions for Adobe Commerce that expose their own GraphQL schemas. These schemas are separate from the [core Commerce GraphQL schema](../index.md) and optimized for fast, read-only storefront rendering. +In Adobe Commerce on cloud and on-premises instances (PaaS), the merchant installs the Storefront Services extensions to enable these GraphQL endpoints. In Adobe Commerce as a Cloud Service (SaaS), the services are installed automatically. + ## 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: @@ -44,8 +46,8 @@ Storefront Services queries do **not** use the standard Commerce GraphQL endpoin | --- | --- | --- | | PaaS | Testing | `https://catalog-service-sandbox.adobe.io/graphql` | | PaaS | Production | `https://catalog-service.adobe.io/graphql` | -| SaaS | Testing | `https://na1-sandbox.api.commerce.adobe.com/{{tenant-id}}/graphql` | -| SaaS | Production | `https://na1.api.commerce.adobe.com/{{tenant-id}}/graphql` | +| SaaS | Testing | `https://{{location}}-sandbox.api.commerce.adobe.com/{{tenant-id}}/graphql` | +| SaaS | Production | `https://{{location}}.api.commerce.adobe.com/{{tenant-id}}/graphql` | ### Different HTTP headers @@ -53,13 +55,12 @@ These services use SaaS context headers instead of the authentication tokens use | Header | Required by | Description | | --- | --- | --- | +| `Magento-Customer-Group` | Catalog Service, Product Recommendations | Customer group for personalized pricing | | `Magento-Environment-Id` | All three services | The SaaS Data Space ID from the Commerce Admin | | `Magento-Store-Code` | All three services | Store code | | `Magento-Store-View-Code` | All three services | Store view code | | `Magento-Website-Code` | All three services | Website code | -| `X-Api-Key` | Catalog Service, Product Recommendations | Unique API key for your Commerce environment | -| `X-Api-Key: search_gql` | Live Search | Fixed value required for Live Search requests | -| `Magento-Customer-Group` | Catalog Service, Product Recommendations | Customer group for personalized pricing | +| `X-Api-Key` | All three services | Unique API key for your Commerce environment | ### Different data types @@ -87,7 +88,7 @@ Storefront Services schemas contain only queries. All mutations (cart, checkout, - 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; Storefront 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. In this case, 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. +- The Storefront Services extensions are not installed or your Commerce instance is not connected to Adobe's SaaS platform. ## How Storefront Services differ from Adobe Commerce Optimizer @@ -102,6 +103,8 @@ Adobe Commerce Optimizer is a standalone SaaS platform that is not installed as | **Context model** | Store view and website codes from Commerce | Catalog views and policies defined in Commerce Optimizer | | **Authentication** | `X-Api-Key` tied to your Commerce environment | No API key required; context is provided through `AC-View-Id` | +Commerce projects deployed on Adobe Commerce on cloud or on-premises can use the [Commerce Optimizer Connector](https://experienceleague.adobe.com/en/docs/commerce/aco-optimizer-connector/overview) to synchronize Commerce catalog data to an Adobe Commerce Optimizer instance. When the connector is installed and enabled, customers use the Merchandising Services GraphQL queries to retrieve product and catalog data instead of using the Catalog Service, Live Search, and Product Recommendations queries. The retrieve data for product discovery, recommendations, projects deployed on Commerce as a Cloud Service must use Storefront Services. + ### Different headers Commerce Optimizer uses a different set of context headers that reflect its catalog-view model: @@ -133,7 +136,7 @@ Use the Commerce Optimizer Merchandising GraphQL API instead of Storefront Servi - 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. +- Your Commerce on cloud infrastructure or on premises project has been configured to use the [Adobe Commerce Optimizer Connector](https://experienceleague.adobe.com/en/docs/commerce/aco-optimizer-connector/overview), which syncs data from your Commerce project to Adobe Commerce Optimizer. If you are running Adobe Commerce (PaaS or SaaS) with the Storefront Services extensions installed, use the Storefront 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. From 3fbb53275642658120e2cea4324b87d228c22c8d Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Fri, 3 Apr 2026 10:48:17 -0500 Subject: [PATCH 5/8] Apply suggestions from code review Co-authored-by: Margaret Eker --- .../graphql/schema/storefront-services/index.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/src/pages/graphql/schema/storefront-services/index.md b/src/pages/graphql/schema/storefront-services/index.md index 3385b5d65..8869addb7 100644 --- a/src/pages/graphql/schema/storefront-services/index.md +++ b/src/pages/graphql/schema/storefront-services/index.md @@ -13,7 +13,7 @@ keywords: Adobe Storefront Services—[Catalog Service](../catalog-service/), [Live Search](../live-search/), and [Product Recommendations](../product-recommendations/)—are SaaS extensions for Adobe Commerce that expose their own GraphQL schemas. These schemas are separate from the [core Commerce GraphQL schema](../index.md) and optimized for fast, read-only storefront rendering. -In Adobe Commerce on cloud and on-premises instances (PaaS), the merchant installs the Storefront Services extensions to enable these GraphQL endpoints. In Adobe Commerce as a Cloud Service (SaaS), the services are installed automatically. +In Adobe Commerce on cloud and on-premises instances (PaaS), the merchant installs and configures the Storefront Services extensions to enable these GraphQL endpoints. In Adobe Commerce as a Cloud Service (SaaS), the services are included in the platform, and the merchant must configure Live Search and Product Recommendations services. ## How the three services relate to each other @@ -103,7 +103,9 @@ Adobe Commerce Optimizer is a standalone SaaS platform that is not installed as | **Context model** | Store view and website codes from Commerce | Catalog views and policies defined in Commerce Optimizer | | **Authentication** | `X-Api-Key` tied to your Commerce environment | No API key required; context is provided through `AC-View-Id` | -Commerce projects deployed on Adobe Commerce on cloud or on-premises can use the [Commerce Optimizer Connector](https://experienceleague.adobe.com/en/docs/commerce/aco-optimizer-connector/overview) to synchronize Commerce catalog data to an Adobe Commerce Optimizer instance. When the connector is installed and enabled, customers use the Merchandising Services GraphQL queries to retrieve product and catalog data instead of using the Catalog Service, Live Search, and Product Recommendations queries. The retrieve data for product discovery, recommendations, projects deployed on Commerce as a Cloud Service must use Storefront Services. +Commerce projects deployed on Adobe Commerce on cloud or on-premises can use the [Commerce Optimizer Connector](https://experienceleague.adobe.com/en/docs/commerce/aco-optimizer-connector/overview) to synchronize Commerce catalog data to an Adobe Commerce Optimizer instance. When the connector is installed and enabled, customers use the Merchandising Services GraphQL queries to retrieve product and catalog data instead of using the Catalog Service, Live Search, and Product Recommendations queries. + +Commerce projects deployed on Commerce as a Cloud Service must use Catalog Service, Live Search, and Product Recommendations queries to retrieve catalog data for product listing, product discovery, and product recommendations. ### Different headers @@ -119,16 +121,17 @@ Commerce Optimizer uses a different set of context headers that reflect its cata The Merchandising GraphQL API provides queries that are similar in name to some Merchant Services queries but are not identical in structure or behavior: -| Query | Merchant Services | Commerce Optimizer | +| Query | Storefront Services | Commerce Optimizer | | --- | --- | --- | -| `products` | Catalog Service — fetch by SKU, returns `ProductView` | Same name, same general purpose, but uses `AC-View-Id` context | +| `products` | Catalog Service — fetch by SKU, returns `ProductView` | Same name, same general purpose, but uses `AC-View-Id` context. Commerce Optimizer also supports an additional `CategoryProductView` interface that returns category information associated with a product, including hierarchical parent relationships and images. | | `productSearch` | Live Search / Catalog Service — full search with `phrase`, `filter`, `sort`, optional `context` | Similar structure, but context is provided through headers rather than a `context` input object | | `attributeMetadata` | Live Search — returns filterable and sortable attributes | Same name and purpose; independent implementation | | `refineProduct` | Catalog Service — narrow complex product options by selection | Equivalent query available | | `variants` | Catalog Service — return all variant combinations | Equivalent query available | | `categories` | Catalog Service — return category hierarchy | Commerce Optimizer uses `categoryTree` with `family` and `slugs` arguments | -| `recommendations` | Product Recommendations — returns units by recommendation type | Commerce Optimizer uses `recommendationsByUnitIds`, which requires pre-configured unit IDs | -| _(none)_ | Not available in Merchant Services | `navigation` — returns category-based navigation structure | +| `recommendations` | Product Recommendations — returns units by recommendation type | Commerce Optimizer supports an equivalent `recommendations` query. Additionally, Optimizer provides a `recommendationsByUnitIds`query, which returns specific recommendation units based on pre-configured unit IDs | +| `navigation` | Not available in Storefront Services | Returns category-based navigation structure for a given product family. | +|` ### When to use Commerce Optimizer From 1c221fb781c37b9bb7fc4cf078e31db39529aa49 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Wed, 8 Apr 2026 15:56:55 -0500 Subject: [PATCH 6/8] updates to storefront services topic --- .../schema/storefront-services/index.md | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/src/pages/graphql/schema/storefront-services/index.md b/src/pages/graphql/schema/storefront-services/index.md index 8869addb7..d12b916f9 100644 --- a/src/pages/graphql/schema/storefront-services/index.md +++ b/src/pages/graphql/schema/storefront-services/index.md @@ -123,15 +123,21 @@ The Merchandising GraphQL API provides queries that are similar in name to some | Query | Storefront Services | Commerce Optimizer | | --- | --- | --- | -| `products` | Catalog Service — fetch by SKU, returns `ProductView` | Same name, same general purpose, but uses `AC-View-Id` context. Commerce Optimizer also supports an additional `CategoryProductView` interface that returns category information associated with a product, including hierarchical parent relationships and images. | -| `productSearch` | Live Search / Catalog Service — full search with `phrase`, `filter`, `sort`, optional `context` | Similar structure, but context is provided through headers rather than a `context` input object | -| `attributeMetadata` | Live Search — returns filterable and sortable attributes | Same name and purpose; independent implementation | -| `refineProduct` | Catalog Service — narrow complex product options by selection | Equivalent query available | -| `variants` | Catalog Service — return all variant combinations | Equivalent query available | -| `categories` | Catalog Service — return category hierarchy | Commerce Optimizer uses `categoryTree` with `family` and `slugs` arguments | -| `recommendations` | Product Recommendations — returns units by recommendation type | Commerce Optimizer supports an equivalent `recommendations` query. Additionally, Optimizer provides a `recommendationsByUnitIds`query, which returns specific recommendation units based on pre-configured unit IDs | -| `navigation` | Not available in Storefront Services | Returns category-based navigation structure for a given product family. | -|` +| [`products`](../catalog-service/queries/products.md) | Catalog Service — fetch by SKU, returns `ProductView` | Same name, same general purpose, but uses `AC-View-Id` context. Commerce Optimizer also supports an additional `CategoryProductView` interface that returns category information associated with a product, including hierarchical parent relationships and images. | +| [`productSearch`](../live-search/queries/product-search.md) | Live Search / Catalog Service — full search with `phrase`, `filter`, `sort`, optional `context` | Similar structure, but context is provided through headers rather than a `context` input object. | +| [`attributeMetadata`](../live-search/queries/attribute-metadata.md) | Live Search — returns filterable and sortable attributes | Same name and purpose; independent implementation | +| [`refineProduct`](../catalog-service/queries/refine-product.md) | Catalog Service — narrow complex product options by selection | Equivalent query available | +| [`variants`](../catalog-service/queries/product-variants.md) | Catalog Service — return all variant combinations | Equivalent query available | +| [`categories`](../catalog-service/queries/categories.md) | Catalog Service — return category hierarchy | Commerce Optimizer uses `categoryTree` with `family` and `slugs` arguments. | +| [`recommendations`](../product-recommendations/queries/recommendations.md) | Product Recommendations — returns units by recommendation type | Commerce Optimizer supports an equivalent `recommendations` query. Additionally, Optimizer provides a `recommendationsByUnitIds` query. | + +Adobe Commerce Optimizer also provides additional queries that are not available in Storefront Services: + +| Query | Description | +| --- | --- | --- | +| `categoryTree` | Retrieves category tree nodes, optionally filtered by slugs and limited by depth. It can return full hierarchy metadata, descriptions, images, and SEO fields.| +| `navigation` | Returns category-based navigation structure for a given product family. It is intended for rendering storefront menus. | +| `recommendationsByUnitIds` | Returns recommendation units based on pre-configured unit IDs. This allows merchants to define specific recommendation sets in Commerce Optimizer and retrieve them directly, rather than relying on real-time AI generation. | ### When to use Commerce Optimizer From 8519beae977bc24a6905b4997a83e1fa70bed3e9 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Thu, 9 Apr 2026 14:36:28 -0500 Subject: [PATCH 7/8] Apply suggestion from @meker12 --- src/pages/graphql/schema/storefront-services/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/graphql/schema/storefront-services/index.md b/src/pages/graphql/schema/storefront-services/index.md index d12b916f9..801c3b78b 100644 --- a/src/pages/graphql/schema/storefront-services/index.md +++ b/src/pages/graphql/schema/storefront-services/index.md @@ -141,7 +141,7 @@ Adobe Commerce Optimizer also provides additional queries that are not available ### When to use Commerce Optimizer -Use the Commerce Optimizer Merchandising GraphQL API instead of Storefront Services queries when: +Use the [Commerce Optimizer Merchandising GraphQL API](https://developer.adobe.com/commerce/services/optimizer/merchandising-services/using-the-api/) instead of Storefront Services queries when: - 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. From f67c743bf69b89afb9294760b85475ab879190a8 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Mon, 13 Apr 2026 15:05:02 -0500 Subject: [PATCH 8/8] Apply suggestion from @meker12 --- src/pages/graphql/schema/storefront-services/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/graphql/schema/storefront-services/index.md b/src/pages/graphql/schema/storefront-services/index.md index 801c3b78b..1587e1303 100644 --- a/src/pages/graphql/schema/storefront-services/index.md +++ b/src/pages/graphql/schema/storefront-services/index.md @@ -92,7 +92,7 @@ Storefront Services schemas contain only queries. All mutations (cart, checkout, ## How Storefront 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. +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](https://developer.adobe.com/commerce/services/reference/graphql/)**, which covers a similar set of storefront use cases but with a different architecture, different query signatures, and different headers. ### Architectural difference