data-slots=text

data-backgroundColor=green

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,categories, product and category 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:

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.

data-variant=info

data-slots=text

Get your endpoint URL and tenant ID

data-src=../../includes/authentication/get-tenant-id.md

Authentication

Authentication is not required for the Merchandising API by default.

A catalog view with Catalog Protection enabled and at least one Restricted Access Key assigned is called a Private Catalog View. Requests to a Private Catalog View must include a valid, signed JSON Web Token (JWT) in the X-Commerce-Access-Token header. Adobe Commerce Optimizer validates the token's RS256 signature against the Restricted Access Keys assigned to the catalog view and returns data only if the signature is valid and neither the token nor the key has expired.

Generating the RSA key pair, signing the token, and configuring Restricted Access Keys are the responsibility of your client application. The public key you register with Adobe Commerce Optimizer must be PEM-encoded RSA, between 2048 and 8192 bits; the matching private key signs each JWT and should never leave your system. See Restricted access keys and Protect a catalog view for setup steps.

A request to a Private Catalog View without a valid token returns a GraphQL error instead of data:

{
  "errors": [
    {
      "message": "Access key validation failed: Missing token",
      "extensions": { "x-commerce-exception": "access-key-invalid" }
    }
  ]
}

The message field describes why validation failed:

A token that has passed its own expiration (the exp claim) is denied the same way, even if the signature would otherwise validate.

Headers

When making requests to the Merchandising 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.

curl --request POST \
--url https://na1-sandbox.api.commerce.adobe.com/{{tenantId}}/graphql \
--header 'AC-View-ID: {{catalogViewId}}'  \
--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.

   curl -X POST \
     'https://na1-sandbox.api.commerce.adobe.com/{{tenantId}}/graphql' \
     -H 'Content-Type: application/json' \
     -H 'AC-View-ID: {{catalogViewId}}' \
     -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.

   If the catalog view specified by AC-View-ID is a Private Catalog View, add the X-Commerce-Access-Token header with a valid signed JWT to the request. See Authentication for how the token is generated and validated.

   curl --request POST \
   --url https://na1-sandbox.api.commerce.adobe.com/{{tenantId}}/graphql \
   --header 'AC-View-ID: {{catalogViewId}}'  \
   --header 'AC-Price-Book-ID: {{priceBookId}}'  \
   --header 'X-Commerce-Access-Token: {{accessToken}}'  \
   --data '{{apiPayload}}'
   

   Table
   Placeholder name	Description
   accessToken	Required for Private Catalog Views. The signed JWT proving authorization to access the catalog view specified by catalogViewId, for example eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9....

   Omitting this header, or supplying an invalid or expired token, returns the GraphQL error shown in Authentication instead of catalog data.

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