Setup guide

This is for:

Merchandising Hub Implementer System Administrator Developer

To properly leverage Coveo for Commerce capabilities, it’s essential that your Coveo organization is optimally configured to integrate with the Commerce API. This setup also enables you to manage Coveo-powered search, product listing pages (PLPs), and recommendation slots through the Coveo Merchandising Hub (CMH).

This guide provides an overview of the Coveo for Commerce implementation process. It contains collapsible sections that you can expand to learn more about each aspect of the implementation. It also includes links to additional articles with detailed instructions on how to complete specific tasks.

This guide covers the following topics:

Map your storefront architecture to Coveo

To effectively index your product inventory, track commerce events, use the Commerce API, and manage product discovery through the Coveo Merchandising Hub (CMH), you need to map your storefronts in a way that’s compatible with Coveo.

In Coveo for Commerce, storefronts are organized into properties, and each property can support multiple locales. For example, if you have two storefronts—one in Canada and one in the United States—your Coveo organization would include two properties, one for each storefront.

Each property can have multiple locales. For example, if your Canadian storefront supports both English and French, you would have two locales under the Canadian property. Each storefront/locale combination would have its own Catalog source and catalog entity representing the products available for that specific combination.

The following diagram shows how the Barca brand’s storefront architecture could be set up in Coveo for Commerce, considering the following variations:

  • Two storefronts: Canada storefront and USA storefront

  • Two supported currencies: CAD and USD

  • Supported languages for each storefront:

    • Canada storefront: English and French

    • USA storefront: English and Spanish

Diagram showing the declination of storefront setup to Coveo’s standards | Coveo for Commerce

Expand the following sections to learn more about the different concepts that you must consider when mapping your storefront architecture to Coveo. Note that you won’t implement these concepts right away, but you should be aware of them to ensure that your storefronts are set up correctly in Coveo.

Tracking ID

Tracking ID

tracking IDs are unique identifiers that identify specific storefronts in usage analytics events. All of your storefronts must have their own tracking ID.

While tracking ID values are specified when sending usage analytics events, each value that’s sent must be registered using a Property in your Coveo organization. See Properties for more information.

In the context of the CMH, the management of the product discovery solutions is segmented by tracking ID. This means that merchandising actions, such as boosting products or creating rules, are specific to each tracking ID.

See What’s a tracking ID? for more information about tracking IDs.

Properties

Properties

Properties allow the management of tracking IDs within a Coveo organization. A property consists of a user-readable display name that simplifies the management and analysis of data across different sites or applications.

Each of your storefronts must have its own property so you can manage the tracking ID associated with it.

Although tracking ID values are specified when sending usage analytics events, properties are managed through the Properties (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console.

Each tracking ID used in your usage analytics events must be registered as a property in your Coveo organization to allow for proper data tracking and interpretation.

Example

Your Coveo organization powers two brands that each have their own storefronts: Barca sports and Barca parts.

Usage analytics events logged from these storefronts are sent with the following tracking IDs:

  • barca_sports_us

  • barca_sports_ca

To allow for accurate data tracking and analysis, you create two properties to register these tracking IDs:

  • Barca Sports US

  • Barca Sports CA

For more information on how to manage properties, see Properties.

Locale

Locale

A given storefront can support many languages, countries, and/or currencies, resulting in variations in product attributes like names, descriptions, and prices.

The Coveo Platform addresses this complexity by utilizing locales to distinguish unique combinations of language, country, and currency.

Locales are defined by a combination of the values of the language, country, and currency parameters sent in Commerce API requests.

Locales allow for reporting according to the language, country, and currency of the user’s experience, as well as managing product discovery solutions for each language, country, and currency permutation within the CMH.

Notes

  • A storefront can have multiple locales associated with it.

  • Locales are storefront parameters, not visitor browser parameters. For example, if a visitor's browser default language is set to German, and they’re browsing an English site, the locale language is en.

    Similarly, a visitor located in Germany browsing a US-based storefront that sells products in American dollars would have their locale tracked with the country set to US and the currency set to USD, even though they’re physically located in a country that uses a different currency.

Locales are defined for every potential combination of supported language, country, and currency that your storefronts support.

Example

Your Coveo organization powers two brands: Barca sports and Barca parts.

You operate in two different countries: United States and Canada. In the United States, you only support English, and in Canada, you support both English and French.

Therefore, you have three different locales:

  • en-US-USD

  • en-CA-CAD

  • fr-CA-CAD

Index your catalog data

To make your product inventory available in the Coveo ecosystem, you need to add your product content to the Coveo index. Typically, this content is stored in repositories such as product information management systems (PIMs) and digital asset management systems (DAMs) in your own ecosystem.

To ensure a successful Coveo for Commerce implementation, it’s necessary to aggregate and format this content in a way that can be read and understood by Coveo. Bringing your product inventory to the Coveo ecosystem and maintaining it involves the following steps:

  • Creation of index sources.

  • Configuration and mapping of commerce fields.

  • Streaming your content to the sources using the Stream API.

  • Creation of a catalog entity.

  • Updating the content using the different update operations offered by the Push API.

The articles of the Index and manage catalog data collection cover each steps in details, but this section provides an high-level overview of everything that’s required to have your product inventory in Coveo and maintaining it.

Expand the following sections to learn more about the different steps required to index and maintain your product inventory in Coveo for Commerce:

Index sources

Index sources

To index your product inventory to the Coveo ecosystem, you’ll typically use a Catalog source.

It’s recommended to create separate product sources for each locale you’re supporting (variations in country, languages, and currency)[1].

This allows the Coveo ML models to learn independently from each experience. Such a setup will result in recommendations that are optimally personalized to users' preferences and search behavior on each website in your multi-catalog structure.

Example

The company Barca sells products in Canada and the US. In Canada, they support French and English. In the US, they support English and Spanish.

They have the following storefronts:

  • Barca Canada (www.barca.com/ca/). This storefront supports French (www.barca.com/ca/fr/) and English (www.barca.com/ca/en/).

  • Barca US (www.barca.com/us/). This storefront supports English (www.barca.com/us/en/) and Spanish (www.barca.com/us/es/).

This setup requires the creation of four product sources:

  • One for the English variation of the Canadian storefront.

  • One for the French variation of the Canadian storefront.

  • One for the English variation of the US storefront.

  • One for the Spanish variation of the US storefront.

Note

Some setups require an additional source to index items of the availability catalog object. See Source configuration approaches for availability channel for details.

1. Having a separate source for each locale you’re supporting will likely lead to content duplication. This could affect your product entitlements.

For instructions on how to create Catalog sources, see Add a Catalog source.

Configure and map commerce fields

Configure and map commerce fields

It’s essential to configure and map your commerce fields to ensure that your product inventory is properly indexed and that the Coveo Machine Learning models can learn from your data. These fields contain metadata, such as the product name or price.

To learn how to configure and map commerce fields, see Commerce fields.

Streaming content

Streaming content

To add content to your Catalog sources, you’ll have to use the Stream API.

You’ll likely use the Stream API in two different stages of your Coveo for Commerce implementation:

  1. To push a sample of your catalog data to your source for the first time.

  2. To push your entire catalog data to your source.

For instructions on how to use the Stream API, see Stream your catalog data to your source.

Catalog entities

Catalog entities

The catalog entity is at the core of a Coveo for Commerce implementation. It establishes relationships between the catalog objects. A catalog entity also lets you standardize your commerce fields to ensure data reliability for Coveo Machine Learning (Coveo ML) models.

There’s a 1-to-1 relationship between product sources and catalog entities. For each source you create that contains products, you must also create a catalog entity. However, sources that only contain items of the availability object type can be shared across multiple catalog entities.

For instructions on how to manage catalog entities, see Commerce catalog entity.

Update content

Update content

Catalog source updates are required when you need to add, remove, or update items (products, variants, or availabilities) in your source after an initial stream.

Coveo offers three update operations to maintain your sources up-to-date with your own product ecosystem:

Configure query pipelines

To ensure that your Coveo for Commerce implementation works seamlessly with the Commerce API, you must configure your query pipelines in the Coveo Administration Console. This allows queries to send the right information to the Commerce API, as well as managing the product discovery solutions that you want to use with the Coveo Merchandising Hub (CMH).

Expand the following sections to learn more about the different aspects of query pipeline configurations:

General query pipeline configuration

Query pipeline configuration

Query pipelines must be created in accordance with the number of properties that your implementation supports. This means that for each registered property, 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:

  • <solution> is the product discovery solution that the query pipeline supports. Allowed values are:

    • search

    • product-listing

    • recommendations

  • <tracking-id> is the tracking ID (registered by a property) that the query pipeline supports.

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 properties:

  • Barca Sports US, which registers the tracking ID barca_sports_us

  • Barca Sports Canada, which registers the tracking ID barca_sports_ca

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

Property Product discovery solution Query pipeline name Query pipeline description

Barca Sports US (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 Canada (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

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 Coveo for Commerce, 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.

Query pipeline filters

Query pipeline filters

In multi-source setups, we recommend that you configure query pipeline filter rules to limit the scope of the query pipeline to the specific source(s) that you want to target. This ensures that queries routed to the pipeline only return results from the intended source(s).

Important

Filters, by themselves, don’t prevent the exposure of filtered content. We strongly advise against creating a source whose content is accessible to everyone and using a pipeline filter to exclude sensitive information.

If availability channels are indexed separately from the product inventory, the filter rules must be configured to include both the product inventory and the availability channels sources.

Example

The Barca Sports Canada storefront has the following sources:

  • French product inventory source: barca_sports_ca_fr

  • English product inventory source: barca_sports_ca_en

  • Availability channels source: barca_sports_ca_availability

For the Search product discovery solution, a query pipeline named cmh-search-barca_sports_ca was created. To ensure this query pipeline only returns results from the correct source, the following filter rules must be configured:

  • Filter rule handling French queries: @source==("barca_sports_ca_fr","barca_sports_ca_availability") This rule should include a pipeline condition that triggers it exclusively for French queries sent to the Commerce API, such as: Context[Locale] is fr-CA-CAD

  • Filter rule handling English queries: @source==("barca_sports_ca_en","barca_sports_ca_availability") This rule should include a pipeline condition that triggers it only for English queries sent to the Commerce API, such as: Context[Locale] is en-CA-CAD

For instructions on how to configure filter rules, see Manage filter rules.

Query pipeline for product listings

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)
Configuring Coveo ML models

Configuring Coveo ML models

To configure the Coveo ML models for product discovery solutions:

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

    Tip

    For optimal results, we recommend that you configure one model of each type for each of your property.

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

    Note

    When associating a PR model with the query pipeline for recommendations, you must configure an association for each of the strategy available in the association flow.

  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 properties for your two Coveo-powered ecommerce sites or applications:

  • Barca Sports US, which registers the tracking ID barca_sports_us

  • Barca Sports Canada, which registers the tracking ID barca_sports_ca

Therefore, you create the following Coveo Machine Learning models:

Property Product discovery solution Model name

Barca Sports US (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 Canada (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 logging commerce events is crucial for feeding models the required data and enhancing relevance over time as more data is collected.

To configure learning filters:

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

For example, if your Coveo for Commerce organization powers multiple websites, the model should only learn from the data of the website on which it’s deployed.

Note

For IAPR and PQS models, instead of defining learning filters, you’ll need to configure the model to use the appropriate tracking IDs (registered as properties in your Coveo organization).

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:

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

    Where you replace <TRACKING-ID> with the tracking ID (registered by a property) 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 registered 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"
}

Define storefront associations

There’s a 1:1 relationship between Catalog sources and catalog entities. This means that you should have one Catalog source and a matching catalog entity for each language, country, currency, and brand you’re selling your products in.

A single tracking ID can apply to multiple locale combinations. For example, if you have a tracking ID identifying a storefront for a brand that sells products in both English and French in Canada, you would have a single tracking ID associated with two locales: en-CA-CAD and fr-CA-CAD.

Storefront associations let you manage the relationship between properties, locales, and catalog entities.

This allows the Coveo Platform to automatically infer the catalog ID targeted by a property and locale combination. So, there’s no need to specify the catalog ID when authenticating commerce requests.

For more information on storefront associations, see Storefront associations.

Build commerce interfaces

Your storefront visitors use commerce interfaces to search, browse, and purchase products. Each of these interfaces is powered by a product discovery solution.

Coveo for Commerce provides three distinct product discovery solutions: Search, Product listings, and Recommendations. It also offers a set of tools to simplify the implementation of your commerce interfaces.

The articles of the Build commerce interfaces collection cover each aspect of building commerce interfaces in details, but this section provides an high-level overview of the different approaches you can take to build commerce interfaces in Coveo for Commerce.

Headless

Headless

The Coveo Headless library is a Redux-based toolset for developing your own UI component libraries. It provides the underlying functionality of the Atomic library without tying that functionality to a specific UI implementation.

We strongly recommend that you use the Headless library rather than work directly with the REST APIs, as Headless abstracts their complexity and provides a more developer-friendly interface.

For more information, see Headless for commerce.

Atomic

Atomic

Important

The Atomic library commerce components are in open beta and therefore under active development. Reach out to your Coveo team for support in adopting them.

The Coveo Atomic library is a collection of pre-built UI components meant to quickly create product discovery interfaces. You can theme and customize the Atomic components to suit your needs. Under the hood, Atomic relies on the Coveo Headless library to interface with Coveo and handle the application state.

Rest APIs

Rest APIs

The Coveo Commerce REST APIs are a set of APIs that allow you to interact with the Coveo Platform.

These APIs offer the most flexibility for interacting with the Coveo Platform, though they require more development effort and can be more challenging to use than Headless or Atomic.

To implement your product discovery solution using the REST APIs, you need to send requests to the following APIs:

  • Commerce API: This API allows you to query the Coveo Platform for products.

  • Event API: This API allows you to log commerce events using the Event Protocol.

After you’ve chosen the right approach, you can start building your search, listing, and recommendation interfaces:

Log commerce events

It’s crucial that you track touchpoints to analyze storefront performance, create reports, and power Coveo Machine Learning (Coveo ML) models. You can do this by sending events to the Coveo Usage Analytics (Coveo UA) service.

Tip

Building commerce interfaces with Coveo UI libraries, such as Coveo Atomic and Coveo Headless, considerably simplifies the implementation of usage analytics tracking.

In Coveo for Commerce, you’ll typically have to track the following user actions:

  • Product views

  • Product clicks

  • Cart events

  • Purchases

It’s through usage analytics tracking that tracking IDs are defined to identify the different storefronts user actions are coming from. Once you’re ready to track these actions, you must register the tracking IDs as properties using the Properties (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console.

For instructions on how to implement usage analytics tracking in Coveo for Commerce, see Log commerce events.