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 must map your storefronts in a way that’s compatible with Coveo.

In Coveo for Commerce, storefronts are organized into properties, each of which can support multiple locales. For example, if you have two storefronts—one in Canada and one in the United States—your 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 US storefront

  • Two supported currencies: CAD and USD

  • Supported languages for each storefront:

    • Canada storefront: English and French

    • US 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 Coveo Analytics events. All of your storefronts must have their own tracking ID.

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

In the context of the Coveo Merchandising Hub (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

Coveo Analytics properties are tracking IDs managed within a Coveo organization. Each property consists of a user-readable display name, enabling simplified management and analysis of data across various sites or applications. properties help you better organize and interpret usage data for specific contexts.

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 Coveo Analytics events, properties are managed through the Properties (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console.

Every tracking ID in your 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 US and Barca sports Canada.

Coveo Analytics events that are 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, or currencies, resulting in variations in product attributes like names, descriptions, and prices.

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

locales allow for reporting according to the language, country, and currency of the user’s experience. You can also use them to manage product discovery solutions for each language, country, and currency permutation within the Coveo Merchandising Hub (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 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, 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.

  • Pushing 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 Stream API.

The articles in the Index and manage catalog data collection cover each step in detail, but this section provides a high-level overview of what’s required to get your product inventory into Coveo and maintain it.

Tip

The resource snapshots feature lets you copy configurations from one Coveo for Commerce organization to another, such as when you migrate from a sandbox to a production organization. It only copies the source configuration, not the source content.

Use this feature to reuse your catalog entities and their catalog configurations, your Catalog sources, and your fields and field mappings.

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

You’ll typically use a Catalog source to index your product inventory into the Coveo ecosystem.

Create separate product sources for each locale you support,[1] so Coveo ML models can learn independently from each experience.

This results 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.sports.barca.group/ca/). This storefront supports French (www.sports.barca.group/ca/fr/) and English (www.sports.barca.group/ca/en/).

  • Barca US (www.sports.barca.group/us/). This storefront supports English (www.sports.barca.group/us/en/) and Spanish (www.sports.barca.group/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.

Fields are also used as attributes to build rules in the Coveo Merchandising Hub (CMH). If you want to use a given field as an attribute in rules, you must enable the Facet or Multi-value facet option for that field.

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

Pushing content

Upload content

To add content to your Catalog sources, you’ll have to use the Stream API. For instructions on how to use the Stream API, see Push and update your catalog data.

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 must add, remove, or update items in your source.

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

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. The Coveo Platform uses them to automatically infer the catalog ID targeted by a property and locale combination, so you don’t need to specify the catalog ID when authenticating commerce requests.

When you define a storefront association, the Coveo Platform will automatically create three query pipelines and their associated conditions, one for each product discovery solution.

Note

If these query pipelines already exist for a given tracking ID, then the Coveo Platform won’t create duplicates.

For example, if your storefront consists of a single site with multiple language and currency options, you’ll associate multiple locales with a single tracking ID. In this case, the Coveo Platform will only create these query pipelines for the first storefront association that you define with this tracking ID.

For more information on storefront associations and these query pipelines, see Storefront associations.

Query pipelines for Product listings

For each query pipeline associated with the Product listings solution, you must configure a ranking weight query pipeline rule to optimize the ranking of products on product listing pages (PLPs).

In this ranking rule, set all the 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) (dedicated model optimized for search)

Intent-Aware Product Ranking (IAPR) (optional)

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

Dynamic Navigation Experience (DNE)

Catalog Semantic Encoder (CSE)

Product listing

Listing Page Optimizer (LPO)

Recommendations

Product Recommendations (PR)

Session-Based Product Recommendations (SBPR) (required to power the Intent-aware product recommendation strategy)
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, you should configure one model of each type for each of your properties.
    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 ART model

    Barca Sports US Search IAPR model

    Barca Sports US Search PQS model

    Barca Sports US Search DNE model

    Barca Sports US Search CSE model

    Listing

    Barca Sports US Listing LPO model

    Recommendations

    Barca Sports US Product Recommendations PR model

    Barca Sports Canada (barca_sports_ca)

    Search

    Barca Sports CA Search ART model

    Barca Sports CA Search IAPR model

    Barca Sports CA Search PQS model

    Barca Sports CA Search DNE model

    Barca Sports CA Search CSE model

    Listing

    Barca Sports CA Listing LPO model

    Recommendations

    Barca Sports CA Product Recommendations PR model

  2. For ART, QS, DNE, and PR models, configure learning filters to ensure they only use data relevant to the website on which they’re deployed. Refer to the articles listed in step 1 for more information on how to configure learning filters for each model type.

    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

  3. Associate the models with the query pipelines that are created when you define your storefront associations. PR and SBPR models require a specific association configuration. See Associate a PR model with a query pipeline for more information.

Migrating search ART, QS, and DNE models

Migrating search ART, QS, and DNE models

Note

This section is only relevant if you’re migrating a Coveo for Commerce implementation that was targeting the Search API to the Commerce API.

If your Coveo for Commerce implementation previously used the Search API and you’re now migrating to the Commerce API, you likely used search hub values to distinguish between different websites. With the Commerce API, tracking IDs now serve this purpose instead.

This transition from search hubs to tracking IDs causes existing models to stop using historical search hub data, meaning the models will rely only on events sent with the new tracking ID. This may lead to a short-term decrease in the model’s performance as it learns from a new set of data.

To maintain performance, you can update your ART, QS, and DNE models' JSON configuration so they continue using both historical search hub data and new tracking ID events.

Important

  • If the model you plan to migrate was used across multiple websites that don’t return the same set of results, don’t migrate the model. Instead, create a new model of each type for each website and configure each model to use the tracking ID associated with its respective website.

  • Models that are used for the Listings product discovery solution can’t be migrated.

To update your ART, QS, and DNE models to use both the search hub value and the tracking ID:

  1. In the Coveo Administration Console, access the Models (platform-ca | platform-eu | platform-au) page.

  2. Click the ART, DNE, or QS model you want to update, and then in the Action bar, click More > Edit JSON.

  3. In the JSON editor, update or add the searchEventFilter parameter to mention the search hub value previously used to identify the storefront, as well as the new tracking ID.

    Your JSON configuration should look like this:

    {
  [...]
  "modelDisplayName": "MY_MODEL",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "exportOffset": "PT0S",
  "commonFilter": "",
  "searchEventFilter": "(originLevel1=~'<MY_SEARCH_HUB>' OR trackingId=~'<MY_TRACKING_ID>')",
  "customEventFilter": "(originLevel1=~'<MY_SEARCH_HUB>' OR trackingId=~'<MY_TRACKING_ID>')",
  [...]
}

    Where:

    • <MY_SEARCH_HUB> is the search hub value previously used to identify the storefront.

    • <MY_TRACKING_ID> is the tracking ID value that now identifies the storefront.

    • The customEventFilter parameter is only required when migrating an ART model.

      Example

      Previously, you used usa-sports-barca as the search hub value to identify a storefront. After migrating to the Commerce API, the storefront is now identified by the tracking ID barca_sports_us.

      To update the model to use both search hub values, you update the model’s JSON configuration as follows:

      {
  [...]
  "modelDisplayName": "MY_MODEL",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "exportOffset": "PT0S",
  "commonFilter": "",
  "searchEventFilter": "(originLevel1=~'usa-sports-barca' OR trackingId=~'barca_sports_us')",
  "customEventFilter": "(originLevel1=~'usa-sports-barca' OR trackingId=~'barca_sports_us')", // If migrating an ART model
  [...]
}

  4. Click Save. The model will retrain and start using both historical search hub data and new tracking ID events.

Warning

Be aware of existing filter conditions and adapt the preceding example accordingly. Also, be sure that any existing originLevel1 logic is preserved and combined with the new trackingId logic.

For example, if your starting point is:

{
  [...]
  "commonFilter": "(originLevel1=~'usa-sports-barca') AND (country=@'canada')",
  [...]
}

You must adapt it to:

{
  [...]
  "commonFilter": "(country=@'canada')",
  "searchEventFilter": "((originLevel1=~'usa-sports-barca') OR (trackingId=~'barca_sports_us'))",
  [...]
}
Tip
Leading practice

Once your model’s data period has passed, you can remove the originLevel1 references from the filters. This is because, at that point, all the old, pre-migration data will have aged out, and the model will only be training on new events that have the trackingId. You’ll also be able to use the trackingId logic in the commonFilter parameter instead of the searchEventFilter and customEventFilter parameters.

For example, if your model’s data period is three months ("exportPeriod": "P3M"), you can remove the originLevel1 references three months after updating the model’s JSON configuration, and add the trackingId logic to the commonFilter parameter as follows:

{
  [...]
  "commonFilter": "(trackingId=~'barca_sports_us')",
  [...]
}

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 detail, but this section provides a 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

Atomic for Commerce components are in open beta and remain under active development.

Atomic for Commerce hasn’t yet gone through a formal accessibility review. If you have accessibility needs, contact your customer success manager and we’ll work with you to address 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.

For more information, see Atomic for commerce.

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