Setup guide

This is for:

Merchandising Hub Implementer System Administrator Developer

The Coveo Merchandising Hub (CMH) offers a convenient solution for ecommerce merchants to manage product discovery for their Coveo for Commerce implementation.

This tool provides merchants with the flexibility to curate products displayed on search results pages, product listing pages, and recommendation slots, that are tailored to various scenarios and requirements.

To begin utilizing the CMH, you must take steps in the Coveo Administration Console to properly configure your Coveo for Commerce implementation.

More precisely, you must:

Notes

  • The CMH isn’t available by default on a Coveo organization. Contact your Coveo Customer Success Manager (CSM) to enable the CMH on your organization.

  • Before starting the CMH implementation, ensure that you’ve properly integrated your product catalog with your Coveo organization.

Query pipeline configuration

To ensure that the CMH works seamlessly with your Coveo for Commerce implementation, you must configure your query pipelines in the Administration Console (platform-ca | platform-eu | platform-au) to support the product discovery solutions that you want to manage through the CMH.

Query pipelines must be created in accordance with the number of tracking IDs that the CMH will support. This means that for each tracking ID, you must create a query pipeline for each product discovery solutions that you’re using.

Query pipelines must follow a strict naming convention, as well as a specific description, which are as follows:

  • Query pipeline name: cmh-<solution>-<tracking-id>

  • Query pipeline description: <solution>-<tracking-id>

Where:

Example

Your Coveo organization powers the Barca sports Coveo-powered commerce implementation.

You operate in two different countries: United States and Canada.

Therefore, you have two tracking IDs:

  • barca_sports_us

  • barca_sports_ca

This means that you would have to create the following query pipelines:

Tracking ID Product discovery solution Query pipeline name Query pipeline description

barca_sports_us

Search

cmh-search-barca_sports_us

search-barca_sports_us

Product listing

cmh-product-listing-barca_sports_us

product-listing-barca_sports_us

Recommendations

cmh-recommendations-barca_sports_us

recommendations-barca_sports_us

barca_sports_ca

Search

cmh-search-barca_sports_ca

search-barca_sports_ca

Product listing

cmh-product-listing-barca_sports_ca

product-listing-barca_sports_ca

Recommendations

cmh-recommendations-barca_sports_ca

recommendations-barca_sports_ca

Query pipeline conditions

You must configure query pipeline conditions to route queries originating from the different product discovery solution interfaces to the correct query pipeline.

Query pipeline conditions are elements that determine which query pipeline to use based on the product discovery solution the end user is interacting with. For example, if a user is interacting with the search interface, the query pipeline condition will route the query to the query pipeline dedicated to search.

In the context of the CMH, query pipeline conditions are built with values of parameters sent to the Commerce API when requesting products using the different endpoints.

Query pipeline conditions must follow a strict naming convention. The naming convention differs based on the product discovery solution that the query pipeline condition supports. The following table provides the naming convention for each product discovery solution:

Product discovery solution Naming convention

Search

Context[commerce-api] is Search and Context[trackingId] is <my_trackingId>

Product listing

Context[commerce-api] is Listing and Context[trackingId] is <my_trackingId>

Recommendations

Context[commerce-api] is Recommendations and Context[trackingId] is <my_trackingId>

Where <my_trackingId> is the value of the tracking ID parameter as used in the request to the Commerce API. For example, when requesting products for your kayaks listing page, the value sent in the trackingId parameter is barca_sports_ca. Therefore, the value of the <my_trackingId> will be barca_sports_ca. See Tracking ID for more information about how to define tracking IDs.

Example

For the barca_sports_ca, you created the following query pipelines:

  • Search query pipeline: cmh-search-barca_sports_ca

  • Listing query pipeline: cmh-product-listing-barca_sports_ca

  • Recommendations query pipeline: cmh-recommendations-barca_sports_ca

The following table provides the query pipeline conditions that you would have to create for each query pipeline:

Product discovery solution Query pipeline Query pipeline condition

Search

cmh-search-barca_sports_ca

Context[commerce-api] is Search and Context[trackingId] is barca_sports_ca

Product listing

cmh-product-listing-barca_sports_ca

Context[commerce-api] is Listing and Context[trackingId] is barca_sports_ca

Recommendations

cmh-recommendations-barca_sports_ca

Context[commerce-api] is Recommendations and Context[trackingId] is barca_sports_ca
Tip
Leading practice

If your Coveo Organization contains query pipelines that route queries that shouldn’t target the Commerce API (that is, query pipelines that target the Search API), we strongly recommend that you add the following condition to the query pipeline:

Context[commerce-api] is not populated

This condition ensures that queries going through the Commerce API don’t target these query pipelines.

For instructions on how to create query pipeline conditions, see Manage query pipeline conditions.

Product listings specific configuration

When configuring the query pipeline for routing product listing queries, you must configure a ranking weight query pipeline rule to optimize the ranking of products on product listing pages.

You must configure the ranking rule to set all ranking factors to 0.

Listings ranking rule in the Coveo Administration Console| Coveo

Machine learning models for Coveo for Commerce

Coveo recommends that you configure Coveo Machine Learning (Coveo ML) models to power and enhance product discovery experiences. To increase personalization and relevancy, configure the recommended Coveo ML models for each of the product discovery solutions:

Product discovery solution Recommended model

Search

Automatic Relevance Tuning (ART) (optimized for search)

Intent-Aware Product Ranking (IAPR) (optional)

Predictive Query Suggestions (PQS) or Query Suggestions (QS)

Dynamic Navigation Experience (DNE)

Product listing

ART (optimized for listing pages)

Recommendations

Product Recommendations (PR)

To configure the Coveo ML models for product discovery solutions:

  1. Configure the appropriate models for each product discovery solution.

    Note

    For optimal results, we recommend that you configure one model of each type for each tracking ID that you’ve defined.

  2. Associate the models with the query pipelines that you’ve created.

  3. For ART, QS, DNE, and PR models, configure learning filters to ensure that the model only uses the data that’s relevant to the website on which it’s deployed.

Example

You’ve defined the following tracking IDs for your two Coveo-powered ecommerce sites or applications:

  • barca_sports_us

  • barca_sports_ca

Therefore, you create the following Coveo Machine Learning models:

Tracking ID Product discovery solution Model name

barca_sports_us

Search

Barca Sports US Search IAPR model

Barca Sports US Search PQS model

Barca Sports US Search DNE model

Listing

Barca Sports US Listing ART model

Recommendations

Barca Sports US Product Recommendations PR model

barca_sports_ca

Search

Barca Sports CA Search IAPR model

Barca Sports CA Search PQS model

Barca Sports CA Search DNE model

Listing

Barca Sports CA Listing ART model

Recommendations

Barca Sports CA Product Recommendations PR model
Note

To effectively power commerce-optimized Coveo ML models, substantial usage analytics data is needed. Properly implementing data tracking is crucial for feeding models the required data and enhancing relevance over time as more data is collected.

Machine learning model configuration for commerce

When using an ART, QS, DNE, or PR model for a Coveo for Commerce organization that powers multiple tracking IDs, you must configure learning filters to ensure that the model uses only the data that’s relevant to the website on which it’s deployed.

For example, if your Coveo for Commerce organization powers multiple websites, you must configure learning filters to ensure that the model only learns from the data of the website on which it’s deployed.

Note

For IAPR and PQS models, instead of defining learning filters, you’ll be required to configure the model to use the appropriate tracking IDs.

Configure the model to use the appropriate tracking ID

To configure learning filters:

  1. Once you’ve created your model, access the Models (platform-ca | platform-eu | platform-au) page.

  2. Click the desired model, and then click More > Edit JSON in the Action bar.

  3. In Edit a Model JSON Configuration, add the following commonFilter object to the JSON configuration:

    "commonFilter": "(c_context_website=@'<TRACKING-ID>')"

    Where you replace <TRACKING-ID> with the tracking ID defined for the website on which you want to use the model.

  4. Click Save.

Example

If you have a model that you want to use on a website for which the tracking ID is barca_sports_us, your JSON configuration should look like this:

{
    "modelDisplayName": "My Commerce ML Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commonFilter": "(c_context_website=@'barca_sports_us')",
    "exportOffset": "PT0S"
}