Set up storefronts and properties

This is for:

System Administrator Developer 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.

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:

For guidance on when to create separate properties versus using locales within a single property, see Determine your property and locale structure.

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.

More precisely, you must use properties to:

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 detailed instructions on adding, editing, and deleting properties, see Properties.

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.

Determine your property and locale structure

Choosing the right structure depends on how much your storefront experiences differ in terms of products and logic.

Create a separate property when

Storefronts require their own product set or high-level logic, such as:

  • Unique product sets: The available products aren’t identical between storefronts (for example, different brands or inventory sets).

  • Different cart experiences: Switching between storefronts affects the customer’s cart (for example, items added on one site don’t carry over to another).

  • Environment differences: The shopping experience differs significantly by region, brand, or device type (for example, app vs. web).

  • Distinct discovery configurations: You need different setups between storefronts for search results, listing pages, or product recommendations.

Use locales within a property when

Your storefronts share the same product set and high-level configuration. locales are ideal for managing differences strictly limited to language, country, or currency without duplicating product discovery logic.

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.