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 (PLPs), and product recommendations in your Coveo-powered commerce site.

The Commerce API is designed to be used with the Coveo Merchandising Hub (CMH), which lets you 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.

However, 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.

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, a Coveo Machine Learning (Coveo 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 (Coveo ML) models.

The Commerce API is a descriptive API that allows the front end to request content without specifying the business logic. This content is managed using various Commerce API endpoints.

Note

For recommendations, under the hood, the CMH configures the response returned by the Commerce API via the Recommendations Configuration endpoints.

Product listing page example

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

Create each PLP on your commerce site using the Product listings manager in the Coveo Merchandising Hub (CMH), which uses the Public Listing Page API under the hood, or by calling this API directly.

Once a PLP has been created, the front end can query it through the Commerce API to return the desired products.

Set up facets for your PLPs using the Facet manager in the Coveo Merchandising Hub (CMH), which uses the Facet Field Configurations API under the hood. If the Facet manager isn’t enabled for your organization, you’ll have set up your facets using the Query Configurations API.

Use the Query Configurations API to specify certain details about the products returned by the Commerce API, including their sort criteria and additional fields. For PLPs, you can create global and specific query configurations, and any settings in a specific configuration override those in the global configuration.

Example

In the global query configuration for PLPs, you specify that you want to sort by relevance. In a specific query configuration for the "Promotions" PLP, you specify that you want to sort by price. This sorting will take precedence over the global setting on that PLP.

Optionally, set up additional rules to apply to the products returned by the Commerce API using the Product listings manager in the Coveo Merchandising Hub (CMH).