---
title: Commerce fields and mapping
slug: oaoe0124
canonical_url: https://docs.coveo.com/en/oaoe0124/
collection: coveo-for-commerce
source_format: adoc
---
# Commerce fields and mapping

When you create a [source](https://docs.coveo.com/en/246/), the [Coveo Platform](https://docs.coveo.com/en/186/) automatically generates a set of [fields](https://docs.coveo.com/en/200/) in your [Coveo organization](https://docs.coveo.com/en/185/) (if they don't already exist).

The type of [source](https://docs.coveo.com/en/246/) you create determines which [fields](https://docs.coveo.com/en/200/) are generated in your [organization](https://docs.coveo.com/en/185/).
For example, if you create a [Catalog source](https://docs.coveo.com/en/l5if0244/), the [Coveo Platform](https://docs.coveo.com/en/186/) generates a set of default [fields](https://docs.coveo.com/en/200/) that are common to all [sources](https://docs.coveo.com/en/246/), such as `language`, `permanentid`, and `uri`.
It also generates a set of commerce-specific [standard](https://docs.coveo.com/en/n73f0502#standard-commerce-fields) [fields](https://docs.coveo.com/en/200/).
If you use a different [source](https://docs.coveo.com/en/246/), you'll need to [configure these commerce-specific fields yourself](#configure-commerce-fields).

To generate [facets](https://docs.coveo.com/en/198/) and power essential features, such as [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/), the [Coveo Platform](https://docs.coveo.com/en/186/) needs your [catalog object](https://docs.coveo.com/en/ncig0154/) information to be held in Coveo [fields](https://docs.coveo.com/en/200/).
You make this information available to the [Coveo Platform](https://docs.coveo.com/en/186/) by [mapping it to specific fields](#map-metadata-keys-to-coveo-fields).
You also have to [map](https://docs.coveo.com/en/217/) certain product [metadata](https://docs.coveo.com/en/218/) to [important default Coveo fields](#important-default-coveo-fields).

## Configure commerce fields

In your [catalog data](https://docs.coveo.com/en/obcf0333/), [catalog object](https://docs.coveo.com/en/ncig0154/) information is represented as [metadata](https://docs.coveo.com/en/218/) keys and values, as shown in the following image:

![Image of a canoe with associated metadata | Coveo for Commerce](https://docs.coveo.com/en/assets/images/coveo-for-commerce/images/canoe-metadata.png)

Before you can [index](https://docs.coveo.com/en/204/) your [catalog data](https://docs.coveo.com/en/obcf0333/), make sure that the following types of [commerce-specific fields](https://docs.coveo.com/en/n73f0502/) are in your [Coveo organization](https://docs.coveo.com/en/185/):

* **Standard** commerce [fields](https://docs.coveo.com/en/200/): These [fields](https://docs.coveo.com/en/200/) are used in all products.
They hold important information, such as the product name, price, and description.
These [fields](https://docs.coveo.com/en/200/) standardize your [catalog data](https://docs.coveo.com/en/obcf0333/) so that [Coveo ML](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/) can learn from expected [field](https://docs.coveo.com/en/200/) data.

> **Note**
>
> If you use a [Catalog source](https://docs.coveo.com/en/l5if0244/), the [Coveo Platform](https://docs.coveo.com/en/186/) automatically generates the standard commerce [fields](https://docs.coveo.com/en/200/).
> However, you still have to [map your catalog object metadata keys to these fields](#map-metadata-keys-to-coveo-fields).

* **Catalog structure** [fields](https://docs.coveo.com/en/200/): These [fields](https://docs.coveo.com/en/200/) represent the structure of your [catalog entity](https://docs.coveo.com/en/3143/).
They're mainly used to categorize commerce items and define their [availability](https://docs.coveo.com/en/mc7e9096/).

* **Custom** [fields](https://docs.coveo.com/en/200/): These [fields](https://docs.coveo.com/en/200/) are used to hold additional product information that's not covered by the standard [fields](https://docs.coveo.com/en/200/).
For example, if you're selling clothing, you might want to create custom [fields](https://docs.coveo.com/en/200/) and [map](https://docs.coveo.com/en/217/) the [metadata](https://docs.coveo.com/en/218/) keys that represent product size and color to these [fields](https://docs.coveo.com/en/200/).

## Important default Coveo fields

Besides the commerce-specific [fields](https://docs.coveo.com/en/200/), the following default [fields](https://docs.coveo.com/en/200/) are important for your Coveo for Commerce implementation:

* `permanentid`: Your [catalog data](https://docs.coveo.com/en/obcf0333/) must contain a [metadata](https://docs.coveo.com/en/218/) key that uniquely identifies each product.
It's crucial that you [map your unique product identifier metadata to this field](https://docs.coveo.com/en/n8of7021#map-to-permanentid).

* `language`: [indexed](https://docs.coveo.com/en/204/) [items](https://docs.coveo.com/en/pa8f6515/) in Coveo for Commerce [organizations](https://docs.coveo.com/en/185/) are too short for automatic language detection.
Even though commerce [sources](https://docs.coveo.com/en/246/) should only contain [items](https://docs.coveo.com/en/pa8f6515/) in a single language, you must [map your language metadata key to this field](https://docs.coveo.com/en/n8of7021#map-to-language).

## Map metadata keys to Coveo fields

_Mapping_ is the process of associating [metadata](https://docs.coveo.com/en/218/) keys from your [catalog data](https://docs.coveo.com/en/obcf0333/) to populate Coveo [fields](https://docs.coveo.com/en/200/).
To populate your [fields](https://docs.coveo.com/en/200/) correctly, you'll need to complete two stages of [metadata](https://docs.coveo.com/en/218/) [mapping](https://docs.coveo.com/en/217/):

* **Catalog configuration mapping**: You define these [mappings](https://docs.coveo.com/en/217/) when you configure your [catalog entity](https://docs.coveo.com/en/3143/).
They only apply to [standard commerce fields](https://docs.coveo.com/en/n73f0502#standard-commerce-fields).

> **Tip**
>
> 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/).
> 
> If you use [any other source](https://docs.coveo.com/en/n8of7021#map-fields-for-other-source-types), you'll still have to define [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/) as well as for any catalog structure or custom [fields](https://docs.coveo.com/en/200/).

The standard [fields](https://docs.coveo.com/en/200/) [mapped](https://docs.coveo.com/en/217/) in the [catalog configuration](https://docs.coveo.com/en/l5if0520/) ensure that:

--
* Coveo has the necessary data to drive its [machine learning](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/).

* [Coveo Analytics events](https://docs.coveo.com/en/260/) logged using the [Event Protocol](https://docs.coveo.com/en/o1n91230/) are enriched with the proper [catalog data](https://docs.coveo.com/en/obcf0333/).
--

* **Source mapping**: You define [source](https://docs.coveo.com/en/246/) [mappings](https://docs.coveo.com/en/217/) to associate the [metadata](https://docs.coveo.com/en/218/) keys from your [source](https://docs.coveo.com/en/246/) with Coveo [fields](https://docs.coveo.com/en/200/).
These [mappings](https://docs.coveo.com/en/217/) are necessary to provide visitors with a rich search experience, such as relevant result templates and [facets](https://docs.coveo.com/en/198/).

> **Important**
>
> 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/), don't
> define [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/):
> 
> * Any [source](https://docs.coveo.com/en/246/) [mappings](https://docs.coveo.com/en/217/) for the standard [fields](https://docs.coveo.com/en/200/) will be overwritten by the [catalog configuration](https://docs.coveo.com/en/l5if0520/) [mappings](https://docs.coveo.com/en/217/).
> 
> * [source](https://docs.coveo.com/en/246/) [mappings](https://docs.coveo.com/en/217/) for these [fields](https://docs.coveo.com/en/200/) can't be used to drive [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) data [models](https://docs.coveo.com/en/1012/).
> 
> You'll still need to define [source](https://docs.coveo.com/en/246/) [mappings](https://docs.coveo.com/en/217/) for any catalog structure or custom [fields](https://docs.coveo.com/en/200/).

For detailed information on how to map your [metadata](https://docs.coveo.com/en/218/) keys to Coveo [fields](https://docs.coveo.com/en/200/), see [Map commerce fields](https://docs.coveo.com/en/n8of7021/).

## Implementation flow

The typical implementation flow for mapping metadata keys to Coveo fields is as follows:

![Field management flow in Coveo for Commerce | Coveo for Commerce](https://docs.coveo.com/en/assets/images/coveo-for-commerce/images/commerce-fields-flow.png)

. [Create your Catalog source](https://docs.coveo.com/en/n8of0593/).

. [Create the commerce fields](https://docs.coveo.com/en/n73f0502/) that you'll [map](https://docs.coveo.com/en/217/) your [metadata](https://docs.coveo.com/en/218/) to.
When using a [Catalog source](https://docs.coveo.com/en/l5if0244/), the [Coveo Platform](https://docs.coveo.com/en/186/) automatically creates the standard commerce [fields](https://docs.coveo.com/en/200/) for you.
You'll need to manually create any structure and custom [fields](https://docs.coveo.com/en/200/) that you require.
Fields are also used as attributes to build rules in the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573/).
If you want to use a given field as an attribute in rules, you must enable the [**Facet** or **Multi-value facet** option](https://docs.coveo.com/en/1833#facet-and-multi-value-facet) for that field.

. [Define your catalog configuration](https://docs.coveo.com/en/3139/).
You'll be required to:

.. Choose the metadata keys that uniquely identify your products, [variants](https://docs.coveo.com/en/mc7f0326/), and [availabilities](https://docs.coveo.com/en/mc7e9096/).
It's important to choose the metadata keys that hold the unique identifiers of items as opposed to the Coveo fields.
For example, if your metadata key for the unique identifier of a product is `product_code`, you must choose the `product_code` metadata key as the product identifier, not the `ec_product_id` field.

![product-code metadata in catalog configuration| Coveo for Commerce](https://docs.coveo.com/en/assets/images/coveo-for-commerce/images/product-code-catalog.png)

.. [Map your metadata keys to Coveo fields in the catalog](https://docs.coveo.com/en/3139#commerce-standard-fields).
For example, Coveo's standard field dedicated to a product's price is `ec_price`.
If your metadata key for the price of a product is `price`, you must map the `price` metadata key to the `ec_price` Coveo standard field.

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

. [Map your metadata keys to standard commerce fields](https://docs.coveo.com/en/n8of7021/) in the index.
While the standard field mappings defined in the catalog configuration is replicated in the index when using a [Catalog source](https://docs.coveo.com/en/l5if0244/), you'll still need to map your metadata keys for any custom fields you've created.

> **Important**
>
> * It's crucial that you [map the metadata key that uniquely identifies your products to the `permanentid` field](https://docs.coveo.com/en/n8of7021#map-to-permanentid).
> 
> * You must also [map the language metadata key in your catalog data to the `language` field](https://docs.coveo.com/en/n8of7021#map-to-language).

. [Index your commerce items](https://docs.coveo.com/en/p48b0322/).