Set up storefronts and properties

This is for:

Developer System Administrator Merchandising Hub Implementer

To track commerce events, use the Commerce API, and manage product discovery solutions through the Coveo Merchandising Hub (CMH), you must map your storefront architecture to the Coveo Platform. This involves planning your tracking IDs, configuring properties, and defining locales for each of your storefronts.

Prerequisites

The following privileges in your Coveo organization are required for the elements in this article.

Action Service Domain Required access level

Create storefront associations

Search

Query pipelines

Create

Commerce

Catalogs

Edit

Analytics

Property

View

Edit storefront associations

Commerce

Catalogs

Edit

View storefront associations

Commerce

Catalogs

View

Storefronts in Coveo

A storefront is the customer-facing part of an online store where visitors browse and purchase products. It represents a single transactional website, encompassing the home page, search, product listing pages (PLPs), product detail page, cart, and checkout process. If your merchandising actions, cart, or checkout processes must differ, you should use separate storefronts, each with its own tracking ID and property.

In the Coveo Platform, each storefront is identified by a unique tracking ID that’s registered as a property. A storefront can support multiple languages, countries, and currencies, each of which is represented by a locale.

Setting up your storefronts in Coveo means mapping your storefront architecture to three key concepts:

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

Storefront architecture for Canada and US with CAD

The following sections cover each of these concepts in detail:

Tracking IDs

A Coveo organization can serve many Coveo-powered commerce sites or applications, but all Coveo Analytics events in a user’s journey should be tied together with a single tracking ID for accurate data analytics and consistency.

tracking IDs segregate the data gathered from each of these sites or applications to ensure personalized and relevant output from your Coveo Machine Learning (Coveo ML) models, usable reporting, and clear merchandising actions.

Each tracking ID points to a specific ecommerce storefront, creating a way to distinguish between distinct sites and their respective user journeys.

The tracking ID is defined when sending events to the Coveo Platform. In interfaces built with the Coveo Headless library or Atomic library, you define it when initializing the commerce engine. Events sent from these interfaces then automatically include the tracking ID. You choose the value, but it must be unique for each storefront and can only contain lowercase letters, numbers, underscores (_), hyphens (-), and periods (.). For example, the following tracking IDs would be valid:

  • barca_sports1_us

  • barca-sports1-us

  • barca.sports1.us

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

Example

Your Coveo organization powers two brands: Barca sports and Barca parts. You operate in two different countries: U.S. and Canada. You decide to have a different site for each brand in each country.

Therefore, you have four different sites that require their own unique tracking ID to be sent with each event:

  • barca_sports_us

  • barca_sports_ca

  • barca_parts_us

  • barca_parts_ca

Each of these tracking IDs is registered using a property in your Coveo organization to ensure that the data is correctly sent:

  • Barca Sports US

  • Barca Sports CA

  • Barca Parts US

  • Barca Parts CA

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.

Use properties to:

Manage properties

Important

Contact your Coveo representative to enable property management from the CMH in your Coveo organization.

Properties can be created and managed from within the Coveo Merchandising Hub (CMH) or from within the Coveo Administration Console.

  • Properties created in the CMH have all the resources required by the storefront automatically generated when the property is published, making this the recommended method.

  • Properties created in the Administration Console require that you define all resources and properly assemble them in order to define a storefront.

Important
Important

The following sections on properties follow the path of a property created in the CMH. If your property was created in the Administration Console, consult the storefront association article.

Property structure

A Coveo organization can have one or more properties.

Each property:

  • Groups the data used to train Coveo Machine Learning (ML) and generate recommendations across its locales.

  • Lets you view analytics for individual locales or for the property as a whole.

  • Lets you apply merchandising controls to individual locales or across the property.

  • Defines which users can access that property in the Coveo Merchandising Hub.

Use a single property for storefront experiences that should share ML models and be managed and reported on together. You can still view reports and apply merchandising controls for individual locales within that property.

Example

Your Coveo organization powers Coffee Canada, a storefront available in English and French. Both language versions send Coveo Analytics events with the tracking ID coffee_canada.

You create a Coffee Canada property in the CMH for that tracking ID, then add two locales: one for English and one for French. Both locales use Canada as the country and Canadian dollars as the currency.

This setup lets ML models learn from activity across both locales. You can view analytics and apply merchandising controls for each locale or for Coffee Canada as a whole.

Each organization can support multiple properties.

Example

Your Coveo organization has two product lines: Coffee Canada and Tea Canada. You want to manage their merchandising separately and keep their analytics and machine learning data distinct.

Events from Coffee Canada use the tracking ID coffee_canada, while events from Tea Canada use tea_canada. You create a property for each tracking ID in the CMH.

This setup lets you view reports, apply merchandising controls, and manage access for each storefront separately. Machine learning models also learn from the activity associated with each property.

Resources generated with a property created in the CMH

When a property is created in the CMH, Coveo also generates the resources required to retrieve catalog content and manage product discovery for the storefront.

Resource Purpose

Tracking ID

The unique identifier that’s used to differentiate and categorize Coveo Analytics data by site or by application.

Catalog

Contains the catalog configuration associated with a locale supported by the property.

Query pipelines

Applies the rules and models used for commerce search queries, product listing queries, and recommendation queries associated with the property.

Storefront association

Connects the property and locale to the corresponding catalog so Coveo can serve the appropriate catalog content in the storefront.

Create a property with the CMH

Important

Contact your Coveo representative to enable property management from the CMH in your Coveo organization.

When you create a property, Coveo uses the site, country, currency, and locale information you provide to generate supporting resources required for the storefront experience.

Important

After a property is published, you will no longer be able to edit its site, countries, currencies, tracking ID, or existing locales. If you must change one of these values, delete the property using the proper protocol and create a new one.

  1. In the CMH, open the Property menu at the top of the page.

  2. Select Create property at the bottom of the dropdown menu.

  3. Complete the property fields.

    • Under Site name, enter the name of the commerce site represented by the property.

    • Under Countries, select the countries supported by the storefront.

    • Under Currencies, select the currencies supported by the storefront.

    • Review the generated Property name and Tracking ID. The property name and tracking ID are generated from the site name and selected countries. They can be edited if needed.

    • Under Reporting currency, select the currency to use for reporting.

    • Under Reporting time zone, select the time zone to use for reporting and scheduling.

  4. Under Locale, define each language, country, and currency combination supported by the storefront:

    • Select the Language the storefront is displayed in.

    • Select the Country the storefront is assigned to.

    • Select the Currency that will be used in the storefront.

    • Repeat for each supported language, country, and currency combination.

    Note

    More locales can be added to a property once it has been published by using the Edit feature.

  5. Click Publish to publish the new property and create the supporting resources.

    • The property becomes available from the Property menu in the top navigation bar.

    • The confirmation window lists resources created for the new property.

  6. Click Close to exit the confirmation window and return to the Overview page.

Example 1: Single property

Your Coveo organization powers Coffee Canada, a storefront available in English and French. Both language versions use Canadian dollars.

In the CMH, create a property with these settings:

  • Site name: Coffee

  • Countries: Canada

  • Currencies: CAD

  • Property name and Tracking ID: Review the values generated from the site name and country.

  • Reporting currency: CAD

  • Reporting time zone: America/Toronto

Then add two locales to the property:

  • English, Canada, CAD

  • French, Canada, CAD

Both locales belong to the same property. This lets you view analytics and apply merchandising controls by locale or for Coffee Canada as a whole.

Example 2: Multiple properties

Your Coveo organization powers two storefronts: Coffee Canada and Tea Canada. Each is available in English and French. You want to manage their analytics, machine learning, and merchandising separately, so you create a property for each storefront.

For the first property, enter Coffee as the site name, then select Canada and CAD. Review the generated property name and tracking ID, set the reporting currency to CAD, and set the reporting time zone to America/Toronto. Add two locales: English, Canada, CAD and French, Canada, CAD.

Repeat the process for the second property, using Tea as the site name. Add the same two locales under that property.

Coffee Canada and Tea Canada now have separate tracking IDs and properties, while each property supports both languages.

Edit a property in the CMH

You can update certain property settings after the property has been published.

  1. In the CMH, open the Property menu at the top of the page.

  2. Select the Edit icon next to the property you want to edit.

  3. Update the available settings:

    • Property name

    • Reporting currency

    • Reporting time zone

  4. Add locales if needed.

    • The Country and Currency options are limited to the values selected when the property was created.

    • Once the property is republished, supporting resources will be created for the new locales.

  5. Click Publish to republish the property.

Delete a property in the CMH

Delete a property when its storefront configuration is no longer needed or when a setting that can’t be edited must be changed.

Important

Deleting a property permanently deletes the property and all of its storefront associations, and invalidates new events sent with its tracking ID.

  1. In the CMH, open the Property menu at the top of the page.

  2. Select the Edit icon next to the property you want to delete.

  3. Click Delete property at the bottom of the Edit Property page.

  4. In the confirmation prompt:

    1. Review the resources that will be permanently deleted.

    2. Enter the prompt indicated in the interface.

    3. Click Delete.

Note

Deleting a property doesn’t delete the catalog entities, catalog configuration, and query pipelines that were generated with it. Review them after deletion and remove or reassign the ones you no longer need.

Locales

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

How to determine your locales

A locale value follows the format language-country-currency (for example, en-US-USD).

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. This occurs even though they’re physically located in a country that uses a different currency.

locales are defined for every supported combination of 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: U.S. and Canada. In the U.S., 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

Similar to tracking IDs, you define locales when sending events to the Coveo Platform. In interfaces built with the Coveo Headless library or Atomic library, you define them when initializing the commerce engine by setting the values of the currency, country, and language parameters. Events sent from these interfaces then automatically include the locale.

What’s next?

Once you’ve planned your tracking IDs, registered your properties, and identified your locales, you’re ready to:

  1. Index and manage catalog data: Create Catalog sources and catalog entities to organize your product data according to your storefronts and locales.

  2. Create storefront associations: Once your catalog entities are in place, connect your properties and locales to the appropriate catalog entities.