How the Commerce API interacts with the CMH

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.

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.

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).

If your Coveo organization uses a multi-region deployment, the Commerce API routes each request based on what that request does.

Query-time requests are routed to your closest deployment region, primary or satellite. These are the requests your storefront makes to serve shoppers, such as search, listing, facet, and recommendation requests. Routing them to a satellite region reduces response times for shoppers located far from your primary region. For the list of routes, see Commerce API routes.

Satellite routing applies only to your organization endpoint (<ORG_ID>.org.coveo.com). Requests to a generic platform endpoint, such as platform.cloud.coveo.com, always go to your primary deployment region.

Administration and configuration requests are always processed in your organization’s primary deployment region, whether they read or write data. Commerce API events are also always processed in the primary region. Because configuration reads and writes both happen in the primary region, a configuration change is visible as soon as you read it back, no matter which region you call from.