How the Commerce API interacts with the CMH

This is for:

Developer

The Commerce API exposes services that let you create search interfaces, product listing pages, and product recommendations in your Coveo-powered commerce site.

The Commerce API is designed to be used with the Coveo Merchandising Hub (CMH), which allows you to configure its behavior. In contrast to the CMH, which is meant for merchandisers, the Commerce API is meant for developers to send requests from the front-end to the Coveo platform.

The Commerce API embraces a fully descriptive API. This approach enhances merchandiser control, standardizes developer implementations, and reduces developer rework once the implementation is complete. Merchandisers gain greater control over their product discovery solutions as business logic shifts to the CMH.

What’s a descriptive API?

A descriptive API requires the consumer to identify a resource and describe the user’s current state, allowing the API to render the response. All business logic resides behind the API, enabling control by the merchandiser, an ML model, or both. This contrasts with Imperative APIs, where the consumer dictates specific actions to the API.

For example, in a descriptive API, the front end requests content for surfboards without specifying facets, ranking rules, sorting criteria, etc. The Coveo Platform responds with the relevant details, such as exactly which facets should be returned and if certain ranking rules need to be applied to the response. These details were configured by the merchandiser in the CMH or left to Coveo Machine Learning models.

The Commerce API is a descriptive API that allows the front end to request content without specifying the business logic.

Note

Under the hood, CMH configures the response returned by the Commerce API via the Configurations endpoints. For more details, see the following endpoints:

Listing page configuration example

Let’s take a look at an example of how listing pages are configured in Coveo to better understand the interaction between the CMH and the Commerce API.

Each listing page on your commerce site is either created using the Coveo Product Listing Manager, which under the hood uses the Listing configuration endpoint, or created by calling this endpoint directly.

This configuration is a JSON object that specifies details such as facets, sort, pinRules, rankingRules, and filterRules that you want to apply to the products returned by the Commerce API.

Once configurations have been created, they can be queried in the front-end by the Commerce API to return the desired products.

Rather than directly querying products with the Commerce API, we strongly recommend using the Coveo Headless library, which abstracts away most of the complexity that comes with working directly with the API.

Global configuration

Additionally, Search and Listing also have the concept of a global configuration. This is the configuration that will be applied if no specific configuration exists.

For example, if in the global configuration for listings you specify that you want a facet on the ec_price, and in remaining listing configurations, you don’t set any facets, a facet on ec_price will be returned by the Commerce API. However, if a specific listing configuration already has facets configured, that will take precedence over the global configuration.

For more details, refer to the following articles: