Edit in GitHubLog an issue
SaaS only

Use cases for the Merchandising API

The Merchandising API supports various e-commerce scenarios. The catalog data delivered by the API is filtered based on the request headers and the catalog view, catalog source, policy, and price book configuration in Adobe Commerce Optimizer. This allows you to create tailored storefront experiences for different customer segments, channels, and regions.

E-commerce Storefronts

  • Product Catalogs: Display product listings with filtering and sorting
  • Search Functionality: Implement product search with autocomplete
  • Product Details: Show comprehensive product information and variants
  • Category Management: Build category navigation trees, menus, and breadcrumbs
  • Recommendations: Display personalized, cross-sell, and upsell product recommendations

Multi-channel Commerce

  • B2B Portals: Customize catalogs for business customers
  • Marketplace Integration: Power third-party marketplace listings
  • Mobile Apps: Provide consistent data across mobile platforms
  • Headless Commerce: Support decoupled frontend architectures

Personalization

  • Customer Segmentation: Deliver targeted product recommendations
  • Regional Pricing: Display locale-specific pricing and availability
  • Dynamic Content: Adapt product displays based on user behavior
  • A/B Testing: Support experimentation with different product presentations

Available Queries

The Merchandising API provides several GraphQL queries designed for different use cases.

QueryDescriptionUse Case
attributeMetadata
Return a list of product attribute codes that can be used for sorting or filtering in a productSearch query
Dynamic filter UIs, sorting options for search and listing pages
categoryTree
Retrieve category tree nodes, optionally filtered by slugs and limited by depth
Category navigation, building category menus, breadcrumbs
navigation
Retrieve the navigation tree for a given product family
Site navigation menus, header and footer navigation
products
Retrieve detailed information about specific products by SKU
Product detail pages, product comparison
productSearch
Search products with filters, sorting, and pagination
Search results, category pages, product listings
refineProduct
Get variant-specific information for configurable products
Product option selection, variant switching
variants
Retrieve all variants of a configurable product
Product detail pages, variant galleries
recommendationsByUnitIds
Retrieve recommendation units by their unique ID to use on the storefront
Display recommendations on the storefront. Supported types include personalized, cross-sell and up-sells, popularity, high-performing Related products, cross-sells, and upsells

Query Examples

The following examples show how to retrieve product information using the product and productSearch queries.

Return product details

The Catalog Service for Adobe Commerce products query returns details about the SKUs specified as input. Although this query has the same name as the products query that is provided with Adobe Commerce, there are some differences.

The Catalog Service query requires one or more SKU values as input. The query is primarily designed to retrieve information to render the following types of content:

  • Product detail pages - You can provide full details about the product identified by the specified SKU.
  • Product compare pages - You can retrieve selected information about multiple products, such as the name, price and image.

The query returns a ProductView output object with the product content values.

Return details about a simple product

The following query returns details about simple product with sku cru-sus-prm-2014. `

Copied to your clipboard
query {
    products(skus: ["cru-sus-prm-2014"]) {
        __typename
        id
        sku
        name
        description
        shortDescription
        addToCartAllowed
        url
        images(roles: []) {
            url
            label
            roles
        }
        attributes(roles: []) {
            name
            label
            value
            roles
        }
        inputOptions {
            id
            title
            required
            type
            markupAmount
            suffix
            sortOrder
            range {
                from
                to
            }
            imageSize {
                width
                height
            }
            fileExtensions
        }
        ... on SimpleProductView {
            price {
                final {
                    amount {
                        value
                        currency
                    }
                }
                regular {
                    amount {
                        value
                        currency
                    }
                }
                roles
            }
        }
        links {
            product {
                sku


            }
            linkTypes
        }
    }
}

Return details about a complex product

The following query returns details about a complex bundled product with sku cru-2014-parts. This bundle provides the optional selections to configure the quality level (standard, midrange, premium) for Cruz Verde 2014 product parts:

  • tires
  • brakes
  • batteries
  • suspension
  • motor

For each part type, the default configuration is to use the standard part quality.

Copied to your clipboard
query GetBundleProductDetails {
  products(skus: "cru-2014-parts") {
    __typename
    id
    sku
    name
    urlKey
    description
    shortDescription
    metaDescription
    metaKeyword
    metaTitle
    lastModifiedAt


    attributes(roles: ["PDP", "PLP", "Search"]) {
      name
      label
      value
      roles
    }
    images(roles: ["image", "small_image", "thumbnail"]) {
      url
      label
      roles
    }
    videos {
      url
      title
      description
      preview {
        url
        label
        roles
      }
    }
    links {
      linkTypes
      product {
        sku
        name
      }
    }
    ... on ComplexProductView {
      options {
        id
        title
        required
        multi
        values {
          id
          title
          inStock
          ... on ProductViewOptionValueProduct {
            quantity
            isDefault
            product {
              __typename
              id
              sku
              name
              description
              shortDescription
              urlKey
              images(roles: ["image", "small_image"]) {
                url
                label
                roles
              }
              attributes(roles: ["PDP"]) {
                name
                label
                value
                roles
              }
            }
          }
          ... on ProductViewOptionValueConfiguration {
            id
            title
            inStock
          }
          ... on ProductViewOptionValueSwatch {
            id
            title
            type
            value
            inStock
          }
        }
      }
    }
  }
}

Product Search

Return information about simple products. This examples uses the productSearch query to return information about battery products for Cruz Verde 2014 models.

Copied to your clipboard
query {
  productSearch(phrase: "Verde battery 2014" page_size: 10) {
    items {
      productView {
        sku
        name
        description
        shortDescription
        images {
          url
        }
        ... on SimpleProductView {
          attributes {
            label
            name
            value
          }
        }
      }
    }
  }
}
Margaret Eker
Last updated 2/25/2026
Was this helpful?

Community

Support

Adobe Developer

  • Privacy
  • Terms of Use
  • Do not sell or share my personal information
  • AdChoices
Copyright © 2026 Adobe. All rights reserved.