Get started with the Merchandising API

Use the Merchandising API to retrieve product data from your Commerce catalogs and display it in Commerce frontend experiences. Data includes products, product attribute metadata, prices books, and prices.

Prerequisites

Before using the Merchandising API, ensure you have:

• Adobe Commerce Optimizer Access: Active subscription and the instance ID associated with your Adobe Commerce Optimizer instance
• Catalog Data: Products and pricing data ingested via the Data Ingestion API
• Catalog Views: Configured views and policies in Adobe Commerce Optimizer
• Authentication Setup: Proper headers configured for API requests
• GraphQL Client: A tool or library to make GraphQL requests (e.g., Postman, Apollo Client, or cURL)
• Familiarity with GraphQL: Basic understanding of GraphQL queries and mutations
• Development Environment: Set up for testing API requests (e.g., local development server or staging environment)

Merchandising API overview

The Merchandising API is a GraphQL API that allows you to access real-time catalog, product discovery, and recommendations data from Adobe Commerce Optimizer. It is designed for backend applications to retrieve product data for use in frontend experiences. All product and price data is stored in a single base catalog that can be filtered and configured to create custom catalogs using Adobe Commerce Optimizer. This approach reduces processing time and improves catalog performance, especially for merchants with large or complex product assortments.

Base URL

Send all Merchandising API requests to this base URL:

Copy
https://na1-sandbox.api.commerce.adobe.com/{{tenantId}}/graphql
Copied to your clipboard
https://na1-sandbox.api.commerce.adobe.com/{{tenantId}}/graphql

The URL structure is:

https://{{region}}-{{environment}}.api.commerce.adobe.com/{{tenantId}}

• region is the cloud region where your instance is deployed.
• environment-type is present only for non-production,sandbox environments.
• tenantId is the unique identifier for your organization's specific instance within the Adobe Experience Cloud.

Authentication

Authentication is not required for the Merchandising API.

Headers

When making requests to the storefront API, you must include required HTTP headers that provide necessary information, such as the catalog view ID, catalog source locale. Additionally, you can include optional policy and price book headers that tailor the API response to your needs.

Request template

Use the following template to submit requests using curl. Use required and optional headers as needed. Replace placeholders with required values.

Copy
curl --request POST \
--url https://na1-sandbox.api.commerce.adobe.com/{{tenantId}}/graphql \
--header 'AC-Environment-Id: {{tenantId}}' \
--header 'AC-View-ID: {{catalogViewId}}'  \
--header 'AC-Source-Locale: {{locale}}' 
--header 'AC-Price-Book-ID: {{priceBookId}}'  \
--header 'AC-Policy-{{attributeCode}}: {{attributeValue}}'  \

--data '{{apiPayload}}'
Copied to your clipboard
curl --request POST \
--url https://na1-sandbox.api.commerce.adobe.com/{{tenantId}}/graphql \
--header 'AC-Environment-Id: {{tenantId}}' \
--header 'AC-View-ID: {{catalogViewId}}'  \
--header 'AC-Source-Locale: {{locale}}' 
--header 'AC-Price-Book-ID: {{priceBookId}}'  \
--header 'AC-Policy-{{attributeCode}}: {{attributeValue}}'  \

--data '{{apiPayload}}'

Get the values for catalog view, policy, catalog source locale, and price book data from the Adobe Commerce Optimizer UI.

Make your first request

To get started with the Merchandising API, follow these steps to make your first request:

1. Get values for the instance ID and required headers.

   • tenantId: Your unique instance ID for Adobe Commerce Optimizer
   • AC-View-ID: Catalog view ID from Adobe Commerce Optimizer

2. Make your first query.

   Use the following example to search for products using the productSearch query, replacing the variable with your own values based on the catalog data and the configuration or your Adobe Commerce Optimizer instance This query retrieves a list of products based on a search term, including their IDs, SKUs, names, and prices.

   Copy
   curl -X POST \
     'https://na1-sandbox.api.commerce.adobe.com/{{tenantId}}/graphql' \
     -H 'Content-Type: application/json' \
     -H 'AC-Environment-ID: {{tenantId}}' \
     -H 'AC-View-ID: {{catalogViewId}}' \
     -H 'Source:Locale: {{locale}}' \
     -d '{"query": "query ProductSearch($search: String!) { productSearch( phrase: $search, page_size: 10) { items { productView { sku name description shortDescription images { url } ... on SimpleProductView { attributes { label name value } price { regular { amount { value currency } } roles } } } } } }", "variables": { "search": "your-string"}}'
   Copied to your clipboard
   curl -X POST \
     'https://na1-sandbox.api.commerce.adobe.com/{{tenantId}}/graphql' \
     -H 'Content-Type: application/json' \
     -H 'AC-Environment-ID: {{tenantId}}' \
     -H 'AC-View-ID: {{catalogViewId}}' \
     -H 'Source:Locale: {{locale}}' \
     -d '{"query": "query ProductSearch($search: String!) { productSearch( phrase: $search, page_size: 10) { items { productView { sku name description shortDescription images { url } ... on SimpleProductView { attributes { label name value } price { regular { amount { value currency } } roles } } } } } }", "variables": { "search": "your-string"}}'

   For sample requests and examples using the API, see the Merchandising API Reference.

Test with the GraphQL Playground

For interactive testing and exploration, use the Adobe Commerce Optimizer API Playground.

Related documentation

• Adobe Commerce Optimizer Guide: Review comprehensive documentation for Adobe Commerce Optimizer.
• Adobe Commerce Storefront Guide: Get help integrating Adobe Commerce Optimizer with an Adobe Commerce storefront on Adobe Edge Delivery Services.
• Adobe Developer App Builder for Commerce: Get documentation for building custom applications to integrate with Adobe Commerce solutions.
• Adobe Commerce Knowledge Base: Search the Adobe Commerce knowledge base for self-service solutions

Last updated 9/22/2025

Was this helpful?

Yes

No