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, price 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 Studio
• 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 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.

However, requests for data from private catalog views configured with catalog protection and restricted access keys must include a valid, signed JSON Web Token (JWT) in the AC-Catalog-View-Access-Token header.

You can set up a private catalog view in Adobe Commece Optimizer Studio by enabling catalog protection and assigning a restricted access key to a catalog view.

• Generate an RSA key pair. The public key must be PEM-encoded and between 2048 and 8192 bits.
• Register the public key as a restricted access key on the catalog view. See Restricted access keys and Protect a catalog view.
• Keep the private key on your system, and use it to sign a JWT for each request.

Adobe Commerce Optimizer validates each token's RS256 signature against the restricted access keys assigned to the catalog view, and returns catalog data only if the signature is valid and neither the token nor the key has expired.

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 date 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, price book , or catalog access view token 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-Catalog-View-Access-Token: {{accessToken}}' 
--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. Replace the variables with values that match your catalog data and your Adobe Commerce Optimizer configuration. 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"}}'
   

   If the catalog view specified by AC-View-ID is a private catalog view, add the AC-Catalog-View-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 'AC-Catalog-View-Access-Token: {{accessToken}}'  \
   --data '{{apiPayload}}'
   

Omitting the AC-Catalog-View-Access-Token header, or supplying an invalid or expired token, returns the GraphQL error shown in Authentication instead of catalog data.

data-variant=info

data-slots=text

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