---
title: Commerce catalog entity
slug: '3139'
canonical_url: https://docs.coveo.com/en/3139/
collection: coveo-for-commerce
source_format: adoc
---
# Commerce catalog entity

The [catalog entity](https://docs.coveo.com/en/3143/) is at the core of a Coveo for Commerce implementation.
It establishes relationships between the [catalog objects](https://docs.coveo.com/en/ncig0154/).
A catalog entity also lets you standardize your commerce fields to ensure data reliability for [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/).

Creating a catalog entity is a requirement for enabling Coveo's machine learning capabilities, maintaining your [catalog data](https://docs.coveo.com/en/obcf0333/), and analyzing [Coveo Analytics data](https://docs.coveo.com/en/259/) through [advanced commerce reporting](https://docs.coveo.com/en/lbtf7260/).

> **Tip**
>
> The [resource snapshots](https://docs.coveo.com/en/3239/) feature lets you copy configurations from one Coveo for Commerce [organization](https://docs.coveo.com/en/185/) 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](https://docs.coveo.com/en/3143/) and their [catalog configurations](https://docs.coveo.com/en/l5if0520/), your [Catalog sources](https://docs.coveo.com/en/l5if0244/), and your [fields](https://docs.coveo.com/en/200/) and field [mappings](https://docs.coveo.com/en/217/).

## Add a catalog entity

There's a 1:1 relationship between a catalog entity and a product source.
This means that each source you created to hold your products must have its own catalog entity.
However, sources that contain only items of the `availability` object type can be shared across multiple catalog entities.

To create a catalog entity:

. On 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 of the [Coveo Administration Console](https://docs.coveo.com/en/183/), click **Add Catalog**.

. Enter a suitable **Name** for your catalog entity (for example, `Barca_Sports_en_US`).

. Under **Object Types**, select the [catalog objects](https://docs.coveo.com/en/ncig0154/) your catalog entity should include:

** If your source only contains [catalog product data](https://docs.coveo.com/en/m53g7119/) objects (without items of the [variant](https://docs.coveo.com/en/mc7f0326/) or [availability](https://docs.coveo.com/en/mc7e9096/) object types), continue to [step 4](#step4).
Note that you can't change the **Object Types** for a catalog entity once it's created.

** If your source contains items of the [`variant` object type](https://docs.coveo.com/en/m53g0506/) to handle different variations of a product, select **Variants**.
Note that if you're solely relying on [product groupings](https://docs.coveo.com/en/m53g0506#product-groupings) to handle different variations of a product, you don't need to select **Variants**.

** If your source contains items of the [`availability` object type](https://docs.coveo.com/en/m53g0124/) to control whether a product or variant is available in a specific channel (for example, a store or a warehouse), select the **Availability** checkbox.

. [[step4]]Under **Catalog Content**, select the [source](https://docs.coveo.com/en/246/) that contains your [catalog data](https://docs.coveo.com/en/obcf0333/) objects.
The source you select can only be used with a single catalog entity.

. Depending on the way you've structured your data, your items of the `availability` object type might be in another source.
In this case, from the dropdown menu, select that source.
Otherwise, clear the **Use a different source for availabilities** checkbox.

. To continue [selecting a configuration for your catalog](#catalog-configuration), click **Next**.

> **Note**
>
> If you need to change the catalog structure, you must create a new catalog entity.
> For example, your catalog entity only had items of the _Product_ catalog object, and now you want to add variants or [availability channels](https://docs.coveo.com/en/mc7e9096/).

## Catalog configuration

A [catalog configuration](https://docs.coveo.com/en/l5if0520/) establishes the relationship between the different [catalog objects](https://docs.coveo.com/en/ncig0154/).
This configuration is re-usable across multiple catalog entities.

When configuring a catalog entity, you can either select an existing catalog configuration or create a new one.

To create a new catalog configuration:

. Click **Create a New Configuration**.

. Enter a suitable **Configuration name**, and then click **Next**.

. Under **Define your products**, select the `objecttype` field value that identifies items as _products_ in your [catalog data](https://docs.coveo.com/en/obcf0333/) (for example, `Product`).

.. Under **Select your Product ID metadata**, select the metadata key that uniquely identifies each distinct product in your [catalog data](https://docs.coveo.com/en/obcf0333/).
Make sure to map this metadata key to the `permanentid` field in your source.
See [Mapping to `permanentid`](https://docs.coveo.com/en/n8of7021#map-to-permanentid) for details.

. If your source contains items of the `Variant` object type, under **Define your variants**, select the `objecttype` field value that identifies items as _variants_ in your [catalog data](https://docs.coveo.com/en/obcf0333/) (for example, `Variant`).

.. Under **Select your Variant ID metadata**, select the metadata key that uniquely identifies each distinct variant in your [catalog data](https://docs.coveo.com/en/obcf0333/).

. Click **Next**.

. If your data hierarchy contains items of the `Availability` object type, under **Define your availabilities**, select the `objecttype` field value that identifies items as _availability channels_ in your [catalog data](https://docs.coveo.com/en/obcf0333/) (for example, `Availability`).

.. Under **Select your Availability ID metadata**, select the metadata key that uniquely identifies each [availability channel](https://docs.coveo.com/en/mc7e9096/) in your [catalog data](https://docs.coveo.com/en/obcf0333/).

.. Under **Select your Available SKUs metadata**, select the multi-value metadata key that lists all sellable items IDs (such as values of `ec_product_id` or `ec_variant_id`), available from each distinct availability channel (for example, `ec_available_items`).

. Click **Next**.

. Under **Map standard fields to your catalog**, map the standard commerce fields to [metadata](https://docs.coveo.com/en/218/) keys from your [catalog data](https://docs.coveo.com/en/obcf0333/).
See the [Commerce standard fields](#commerce-standard-fields) section for more information on this step.

. Click **Finish**.

The catalog entity is now available on 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.

Once your catalog entity is created, [push your catalog data into the source](https://docs.coveo.com/en/p48b0322/) once more.
This ensures that the catalog entity is properly registered and ensures the proper functioning of Coveo ML models.

## Commerce standard fields

In the **Map standard fields to your catalog** step of the [catalog configuration](#catalog-configuration), you'll be asked to [map](https://docs.coveo.com/en/217/) the [standard commerce fields](https://docs.coveo.com/en/n73f0502#standard-commerce-fields) to [metadata](https://docs.coveo.com/en/218/) from your [index](https://docs.coveo.com/en/204/).
This step is critical for:

* Making sure that [Coveo Personalization-as-you-go](https://docs.coveo.com/en/m5kd0347/) (PAYG) can build a [product vector space](https://docs.coveo.com/en/l9gg3565/) that represents your content.

* Tracking [Coveo Analytics events](https://docs.coveo.com/en/260/) using the [Event Protocol](https://docs.coveo.com/en/o1n91230/).
This ensures that commerce [events](https://docs.coveo.com/en/260/) are enriched with the required [catalog data](https://docs.coveo.com/en/obcf0333/), such as `ec_item_group_id`, `ec_category`, and `ec_brand`.

> **Warning**
>
> [catalog configuration](https://docs.coveo.com/en/l5if0520/) [mappings](https://docs.coveo.com/en/217/) aren't the same as [source mappings](https://docs.coveo.com/en/1640/), in which you [map](https://docs.coveo.com/en/217/) [metadata](https://docs.coveo.com/en/218/) from your [source](https://docs.coveo.com/en/246/) to Coveo [fields](https://docs.coveo.com/en/200/).
> 
> If you use a [Catalog source](https://docs.coveo.com/en/l5if0244/) to [index](https://docs.coveo.com/en/204/) your [catalog data](https://docs.coveo.com/en/obcf0333/),
> the
> [standard field mappings](https://docs.coveo.com/en/3139#commerce-standard-fields) defined in the [catalog configuration](https://docs.coveo.com/en/l5if0520/) will overwrite any [source](https://docs.coveo.com/en/246/) [mappings](https://docs.coveo.com/en/217/) for the standard commerce [fields](https://docs.coveo.com/en/200/).

To [map](https://docs.coveo.com/en/217/) the standard commerce [fields](https://docs.coveo.com/en/200/) to your [catalog entity](https://docs.coveo.com/en/3143/), in the **Associated Metadata** column, select the [metadata](https://docs.coveo.com/en/218/) to associate to the standard [fields](https://docs.coveo.com/en/200/).

![Standard fields mapping in catalog configuration | Coveo for Commerce](https://docs.coveo.com/en/assets/images/coveo-for-commerce/images/standard-fields-mapping.png)

If you haven't pushed your commerce data to your [source](https://docs.coveo.com/en/246/) yet, you won't be able to see your [metadata](https://docs.coveo.com/en/218/) keys in the dropdowns of the **Associated Metadata** column.
However, if you know the nomenclature of the [metadata](https://docs.coveo.com/en/218/) keys that you'll be using, you can enter them in the **Associated Metadata** column.

When structuring your [product](https://docs.coveo.com/en/m53g7119/), [variant](https://docs.coveo.com/en/m53g0506/), and [availability](https://docs.coveo.com/en/m53g0124/) data, use the same [field](https://docs.coveo.com/en/200/) names as the standard commerce [fields](https://docs.coveo.com/en/200/) (prefixed with `ec_`, such as `ec_price`).

If your [catalog data](https://docs.coveo.com/en/obcf0333/) uses different names from those the standard [fields](https://docs.coveo.com/en/200/) expect, such as `price`, [map the standard commerce fields](https://docs.coveo.com/en/n8of7021#step-2-standard-fields-mapping-catalog-source) to your [metadata](https://docs.coveo.com/en/218/) in the [catalog configuration](https://docs.coveo.com/en/l5if0520/).

## Edit a catalog entity

You can edit a catalog entity to change its name, the source it uses, the [catalog configuration](https://docs.coveo.com/en/l5if0520/) it's associated with, or the associated facets.

. On 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, click the desired catalog entity, and then click **Edit** in the Action bar.
This will open the **Overview** tab where you can:

** Edit the **Name**.

** Edit the **Description**.

** Edit the **Catalog Content**, where you can update the [source](https://docs.coveo.com/en/246/) that contains your [catalog data](https://docs.coveo.com/en/obcf0333/).
Note that the source you select can only be used with a single catalog entity.

If your catalog entity has availability objects and the way you've structured your data has changed, your availability data might now be contained in another source.
In this case, select the new source from the dropdown menu.
Otherwise, clear the **Use a different source for availabilities** checkbox.

. To review facet associations for this catalog entity, select the **Facet Association** tab.
For more information, see the [Facet Association](#facet-association-tab) section.

. Click **Save**.

. When you're done editing your catalog entity, you must [push your catalog data into the source](https://docs.coveo.com/en/p48b0322/) once more.
This ensures that the catalog entity is properly registered and ensures the proper functioning of Coveo ML models.

### "Facet Association" tab

Using the **Facet Association** tab, you can quickly view which facetable field names exist for each [catalog object](https://docs.coveo.com/en/ncig0154/) type.
The percentage shown represents the ratio of each field by catalog object type.
By hovering over the percentage shown, you can see the number of documents that contain the associated field name.

> **Tip**
>
> Depending on your specific use case, if the percentages deviate from what you expect, this could be an indication that your data isn't properly structured.

In advanced use cases, your data structure may require having the same facetable fields on multiple catalog object types.
For example, you may want to use the same `language` field across all your items.
In this case, the value `@language` would need to appear on all catalog objects (Product, Variant, and Availability) to return matching results.

To access the **Facet Association** tab:

. On 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, click the desired catalog entity, and then click **Edit** in the Action bar.

. Select the **Facet Association** tab.

. Select the desired field, and then click **Edit Field** in the Action bar.
You'll be sent to the **Edit a field** subpage, where you can edit the [field options](https://docs.coveo.com/en/1833#field-options).

. Click **Save**.

. When you're done editing your catalog entity, you must [push your catalog data into the source](https://docs.coveo.com/en/p48b0322/) once more.
This ensures that the catalog entity is properly registered and ensures the proper functioning of Coveo ML models.

. (Optionally) Click **Refresh Field Cache** in the upper-right corner.

This allows you to instantly update the field values you edited instead of waiting for them to update automatically through the staged refresh, which automatically detects the fields that you can use to generate [facets](https://docs.coveo.com/en/1571/) every 15 minutes.
The last update time appears at the lower right of the **Facet Association** tab.

## Delete a catalog entity

On 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, click the desired catalog entity, and then click **Delete** in the Action bar.

## Edit a commerce catalog configuration

Depending on the structure you've created for your commerce environment, you may need to change or delete your configurations.
For example, if you need to redefine which `objecttype` field value identifies as a product in your index.

> **WARNING**
>
> Editing a configuration will impact all associated catalog entities.

. On 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, click **Manage Configurations**.

. Click icon:external-link[alt=external-link,width=16] to edit the configuration.

For more information on how to configure a catalog configuration, refer to the [Catalog configuration](#catalog-configuration) section.

## Delete a commerce catalog configuration

> **Note**
>
> You can't delete a catalog configuration without first deleting the associated catalog entities.
> Once the associated catalog entity is deleted, the previously associated configuration will remain in your **Manage configurations** interface until it's manually deleted.

. On 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, click **Manage Configurations**.

. Click [delete] next to the configuration you want to delete.

## What's next?

After configuring your catalog entity, you must associate it with the target [tracking ID](https://docs.coveo.com/en/o8rb0139/) and [locale](https://docs.coveo.com/en/p4tf0351/) (see [Storefront associations](https://docs.coveo.com/en/o48e0216/)).