--- title: Storefront associations slug: o48e0216 canonical_url: https://docs.coveo.com/en/o48e0216/ collection: coveo-for-commerce source_format: adoc --- # Storefront associations A [storefront](https://docs.coveo.com/en/p33g0410/) association is a [Coveo Platform](https://docs.coveo.com/en/186/) configuration that connects a [catalog entity](https://docs.coveo.com/en/3143/) with a specific [tracking ID](https://docs.coveo.com/en/o8rb0139/) and [locale](https://docs.coveo.com/en/p4tf0351/). The [Coveo Platform](https://docs.coveo.com/en/186/) uses [storefront](https://docs.coveo.com/en/p33g0410/) associations to automatically identify the appropriate catalog ID in queries and to enrich [Coveo Analytics events](https://docs.coveo.com/en/260/) with product [metadata](https://docs.coveo.com/en/218/). Because the platform resolves the appropriate [catalog entity](https://docs.coveo.com/en/3143/) for content retrieval and event enrichment, you don't need to specify the catalog ID when making [queries](https://docs.coveo.com/en/231/) or logging events using the [Event Protocol](https://docs.coveo.com/en/o9je0592/). This allows the [Coveo Platform](https://docs.coveo.com/en/186/) to enrich event data with key [metadata](https://docs.coveo.com/en/218/) from the Coveo catalog, such as `ec_category`, `ec_brand`, and `ec_item_group_id`. This reduces the amount of data you must send and provides more detailed and relevant information for [logged commerce events](https://docs.coveo.com/en/3188/). Storefront associations are required for the proper functioning of Coveo for Commerce implementations. > **Important** > > If you delete a [storefront](https://docs.coveo.com/en/p33g0410/) association, you'll need to recreate any [Coveo Personalization-as-you-go](https://docs.coveo.com/en/m5kd0347/) machine learning model that's linked to the [storefront](https://docs.coveo.com/en/p33g0410/). ## Prerequisites To create a storefront association, you need at least: * A [source](https://docs.coveo.com/en/246/) that holds your product data (for example, a [Catalog source](https://docs.coveo.com/en/l5if0244/)). * A [catalog entity](https://docs.coveo.com/en/3143/) that's linked to the [source](https://docs.coveo.com/en/246/). * A [property](https://docs.coveo.com/en/p4ue0547/). * The following [privileges](https://docs.coveo.com/en/228/) in your [Coveo organization](https://docs.coveo.com/en/185/): [cols="3",options="header"] |=== |Action |Service - Domain |Required access level .3+.^|Create storefront associations |Search - Query pipelines |Create |Commerce - Catalogs |Edit |Analytics - Property |View .2+.^|Edit storefront associations |Commerce - Catalogs |Edit |Analytics - Property |View .2+.^|View storefront associations |Commerce - Catalogs |View |Analytics - Property |View |=== ## Create a storefront association . Access the [**Storefront associations**](https://platform.cloud.coveo.com/admin/#/orgid/commerce/storefront/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/commerce/storefront/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/commerce/storefront/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/commerce/storefront/)) page of the [Coveo Administration Console](https://docs.coveo.com/en/183/). . Click **Create an association**. . Under **Property**, select the [property](https://docs.coveo.com/en/p4ue0547/) tied to the [tracking ID](https://docs.coveo.com/en/o8rb0139/) that identifies the [storefront](https://docs.coveo.com/en/p33g0410/) you want to use for this association. . Under **Locale**, select the [locale](https://docs.coveo.com/en/p4tf0351/) you want to use for this association. A locale is composed of: ** An [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code (for example, `en` for English). ** An [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (for example, `US` for the United States). ** An [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code (for example, `USD` for US dollar). . Under **Catalog**, select the [catalog entity](https://docs.coveo.com/en/3143/) that contains the products for a given [storefront](https://docs.coveo.com/en/p33g0410/) and [locale](https://docs.coveo.com/en/p4tf0351/) combination. . (If available) You can optionally use the **Project** selector to associate your storefront association with one or more [projects](https://docs.coveo.com/en/n7ef0517/). . Click **Save**. **Example** You have two storefronts: one that targets customers in Canada and displays product prices in Canadian dollars, and another storefront that targets customers in the United States and displays product prices in US dollars. To handle these two storefronts, you have two [Catalog sources](https://docs.coveo.com/en/l5if0244/) in your [Coveo organization](https://docs.coveo.com/en/185/): one for the Canadian storefront and another for the US storefront. Therefore, you must create two [storefront](https://docs.coveo.com/en/p33g0410/) associations: * One that links the Canadian storefront's [property](https://docs.coveo.com/en/p4ue0547/) and `en-CA-CAD` [locale](https://docs.coveo.com/en/p4tf0351/) to the Canadian [catalog entity](https://docs.coveo.com/en/3143/). * One that links the US storefront's [property](https://docs.coveo.com/en/p4ue0547/) and `en-US-USD` [locale](https://docs.coveo.com/en/p4tf0351/) to the US [catalog entity](https://docs.coveo.com/en/3143/). ## Storefront associations and query pipelines When you define a [storefront](https://docs.coveo.com/en/p33g0410/) association, the [Coveo Platform](https://docs.coveo.com/en/186/) will automatically create three [query pipelines](https://docs.coveo.com/en/180/) and their associated [conditions](https://docs.coveo.com/en/2793/), one for each [product discovery solution](https://docs.coveo.com/en/o9cf0524/). > **Note** > > If these [query pipelines](https://docs.coveo.com/en/180/) already exist for a given [tracking ID](https://docs.coveo.com/en/o8rb0139/), then the [Coveo Platform](https://docs.coveo.com/en/186/) won't create duplicates. > > For example, if your [storefront](https://docs.coveo.com/en/p33g0410/) consists of a single site with multiple language and currency options, you'll associate multiple [locales](https://docs.coveo.com/en/p4tf0351/) with a single [tracking ID](https://docs.coveo.com/en/o8rb0139/). > In this case, the [Coveo Platform](https://docs.coveo.com/en/186/) will only create these [query pipelines](https://docs.coveo.com/en/180/) for the first [storefront](https://docs.coveo.com/en/p33g0410/) association that you define with this [tracking ID](https://docs.coveo.com/en/o8rb0139/). Each of these [query pipelines](https://docs.coveo.com/en/180/) handle [queries](https://docs.coveo.com/en/231/) sent from one of the [product discovery solution](https://docs.coveo.com/en/o9cf0524/) interfaces that use the [tracking ID](https://docs.coveo.com/en/o8rb0139/) defined in the [storefront](https://docs.coveo.com/en/p33g0410/) association and ensure that these [queries](https://docs.coveo.com/en/231/) send the right information to the Commerce API. The [query pipeline](https://docs.coveo.com/en/180/) names and descriptions use the following format: * **Query pipeline name** (maximum 50 characters): `cmh---` * **Query pipeline description**: `-` where: * `` is the [product discovery solution](https://docs.coveo.com/en/o9cf0524/) that this particular [query pipeline](https://docs.coveo.com/en/180/) supports. The supported values are `search`, `listing`, or `recommendations`. * `` is the [tracking ID](https://docs.coveo.com/en/o8rb0139/) (registered by a [property](https://docs.coveo.com/en/p4ue0547/)) that this [query pipeline](https://docs.coveo.com/en/180/) supports. A [tracking ID](https://docs.coveo.com/en/o8rb0139/) can be up to 100 characters in length, so it may be truncated to fit the [query pipeline](https://docs.coveo.com/en/180/) name's 50-character limit. * `` is a deterministic 8-character hash of the [tracking ID](https://docs.coveo.com/en/o8rb0139/). The inclusion of the [tracking ID](https://docs.coveo.com/en/o8rb0139/) ensures readability (even if truncated), while the hash prevents name collisions. **Example** Your [tracking ID](https://docs.coveo.com/en/o8rb0139/) is `market_27852570855`. After you define a [storefront](https://docs.coveo.com/en/p33g0410/) association, the following [query pipelines](https://docs.coveo.com/en/180/) are created within your [Coveo organization](https://docs.coveo.com/en/185/): [%header,cols="2"] |=== |Name |Description |`cmh-listing-market_27852570855-0f3825a5` |`listing-market_27852570855` |`cmh-search-market_27852570855-0f3825a5` |`search-market_27852570855` |`cmh-recommendations-market_27852570855-0f3825a5` |`recommendations-market_27852570855` |=== ### Query pipeline conditions [query pipeline conditions](https://docs.coveo.com/en/2793/) route [queries](https://docs.coveo.com/en/231/) originating from different [product discovery solution](https://docs.coveo.com/en/o9cf0524/) interfaces to the correct [query pipeline](https://docs.coveo.com/en/180/). For example, when a user sends a [query](https://docs.coveo.com/en/231/) from the search box, the [condition](https://docs.coveo.com/en/2793/) will route the [query](https://docs.coveo.com/en/231/) to the [query pipeline](https://docs.coveo.com/en/180/) dedicated to the Search [solution](https://docs.coveo.com/en/o9cf0524/). These [conditions](https://docs.coveo.com/en/2793/) are configured when the [query pipelines](https://docs.coveo.com/en/180/) are created. They use a naming convention that's based on the [solution](https://docs.coveo.com/en/o9cf0524/) that the [query pipeline](https://docs.coveo.com/en/180/) supports, as shown in the following table: [%header,cols="~,~"] |=== |Product discovery solution |Query pipeline condition |Search |`Context[commerce-api] is Search and Context[trackingId] is ` |Product listings |`Context[commerce-api] is Listing and Context[trackingId] is ` |Recommendations |`Context[commerce-api] is Recommendations and Context[trackingId] is ` |=== where `` is the [tracking ID](https://docs.coveo.com/en/o8rb0139/) used in the request to the Commerce API. **Example** Your [tracking ID](https://docs.coveo.com/en/o8rb0139/) is `market_27852570855`. After you define a [storefront](https://docs.coveo.com/en/p33g0410/) association, your [query pipelines](https://docs.coveo.com/en/180/) have the following conditions: [%header,cols="2"] |=== |Name |Condition |`cmh-search-market_27852570855-0f3825a5` |`Context[commerce-api] is Search and Context[trackingId] is market_27852570855` |`cmh-listing-market_27852570855-0f3825a5` |`Context[commerce-api] is Listing and Context[trackingId] is market_27852570855` |`cmh-recommendations-market_27852570855-0f3825a5` |`Context[commerce-api] is Recommendations and Context[trackingId] is market_27852570855` |=== ### Query pipelines for Product listings For each [query pipeline](https://docs.coveo.com/en/180/) associated with the Product listings [solution](https://docs.coveo.com/en/o9cf0524/), you must [configure a ranking weight](https://docs.coveo.com/en/3412/) [query pipeline rule](https://docs.coveo.com/en/236/) to optimize the ranking of products on [product listing pages (PLPs)](https://docs.coveo.com/en/m1sf3187/). In this ranking rule, set all the ranking factors to `0`. ![Listings ranking rule in the Coveo Administration Console| Coveo](https://docs.coveo.com/en/assets/images/coveo-for-commerce/images/cmh/cmh-implementation-ranking-rule.png) ## Storefront associations and authentication Once you've set up the necessary [storefront](https://docs.coveo.com/en/p33g0410/) associations, you can authenticate both search and analytics requests using a single [search token](https://docs.coveo.com/en/56/) or [API key](https://docs.coveo.com/en/105/) that grants the **Allowed** [access level](https://docs.coveo.com/en/2818/) on the [**Execute Queries**](https://docs.coveo.com/en/1707#execute-queries-domain) [domain](https://docs.coveo.com/en/2819/) and the **Push** [access level](https://docs.coveo.com/en/2818/) on the [**Analytics Data**](https://docs.coveo.com/en/1707#administrate-domain) [domain](https://docs.coveo.com/en/2819/) in the target [Coveo organization](https://docs.coveo.com/en/185/). For more details on authenticating requests, see [Authenticate commerce requests](https://docs.coveo.com/en/o8ld0051/). > **Tip** > > You no longer need to generate API keys through the [**Catalogs**](https://platform.cloud.coveo.com/admin/#/orgid/commerce/catalogs/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/commerce/catalogs/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/commerce/catalogs/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/commerce/catalogs/)) page, which would enforce the catalog ID value in the API keys. > A single [search token](https://docs.coveo.com/en/1346/) or API key can be used across many [catalog entities](https://docs.coveo.com/en/3143/).