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

Commerce [fields](https://docs.coveo.com/en/200/) hold key information about each [item](https://docs.coveo.com/en/pa8f6515/) in your [index](https://docs.coveo.com/en/204/).
They contain [metadata](https://docs.coveo.com/en/218/), such as the product name or price, that power your product discovery experiences with Coveo.

You can use these commerce [fields](https://docs.coveo.com/en/200/) to:

* Provide specific information about each individual product, [variant](https://docs.coveo.com/en/mc7f0326/), or [availability](https://docs.coveo.com/en/mc7e9096/) channel.

* Enforce your product catalog structure.

* Create [facets](https://docs.coveo.com/en/198/) to refine search results.

* Make sure that [Coveo Personalization-as-you-go (PAYG)](https://docs.coveo.com/en/m5kd0347/) [models](https://docs.coveo.com/en/1012/) can leverage [product embeddings and vectors](https://docs.coveo.com/en/l9gg3565/).

* Enrich [Coveo Analytics events](https://docs.coveo.com/en/260/) with the expected [catalog data](https://docs.coveo.com/en/obcf0333/).

When preparing your [catalog data](https://docs.coveo.com/en/obcf0333/) for [indexing](https://docs.coveo.com/en/204/), one of the first steps is to configure these [fields](https://docs.coveo.com/en/200/).

This article explains which [fields](https://docs.coveo.com/en/200/) are required, recommended, and optional to set up in your Coveo for Commerce [organization](https://docs.coveo.com/en/185/).

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

## Standard commerce fields

The standard commerce [fields](https://docs.coveo.com/en/200/) 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/).

When you [create a Catalog source](https://docs.coveo.com/en/n8of0593/) in your [Coveo organization](https://docs.coveo.com/en/185/), the standard commerce [fields](https://docs.coveo.com/en/200/) [are automatically generated](https://docs.coveo.com/en/n8of7021#catalog-configuration-mapping) and can't be changed.
With other [source](https://docs.coveo.com/en/246/) types, you must create these [fields](https://docs.coveo.com/en/200/) yourself.

Make sure to [create mappings](https://docs.coveo.com/en/3139#commerce-standard-fields) for these [fields](https://docs.coveo.com/en/200/) in the [catalog configuration](https://docs.coveo.com/en/l5if0520/).
You must also [map the unique product identifier to the `permanentid` field](https://docs.coveo.com/en/n8of7021#map-to-permanentid).

> **Note**
>
> To train [Coveo ML](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/), you can't use the `#` character in the `ec_product_id` or `permanentid` [fields](https://docs.coveo.com/en/200/).

The following table lists the standard commerce fields and their properties:

[%header,cols="3a,1,3,5a"]
|===
|Field
|Type
|Description
|Usage notes

|`ec_name`[.footnote]^[[1](#name-and-description)]^  
(Required)
|String
|The product's name.
|* Displays the product's name in the result template.

* Enabled field settings:

** [Free text search](https://docs.coveo.com/en/1833#free-text-search)

|`ec_description`[.footnote]^[[1](#name-and-description)]^  
(Required)
|String
|The product's description.
|* Required for producing [product embeddings and vectors](https://docs.coveo.com/en/l9gg3565/).

* Displays the product's description in the result template.

* Enabled field settings:

** [Free text search](https://docs.coveo.com/en/1833#free-text-search)

|[[define-a-unique-product-identifier]] `ec_product_id`[.footnote]^[[2](#unique-product-id)]^  
(Required)
|String
|The product's unique identifier within a single source.
|* Required for ML models and [attribution](https://docs.coveo.com/en/m7l98577/).

* Should hold the same value as the [`permanentid`](https://docs.coveo.com/en/n8of7021#map-to-permanentid) field.

* Enabled field settings:

** [Use cache for nested queries](https://docs.coveo.com/en/1833#use-cache-for-nested-queries).

** [Facet](https://docs.coveo.com/en/1833#facet-and-multi-value-facet)[.footnote]^[[3](#generate-facets-1)]^

|`ec_category`  
(Required)
|String
|The product's category.
|* Required for producing [product embeddings and vectors](https://docs.coveo.com/en/l9gg3565/).

* Displays the product's category in the result template.

* Enabled field settings:

** [Facet](https://docs.coveo.com/en/1833#facet-and-multi-value-facet)[.footnote]^[[3](#generate-facets-1)]^

** [Free text search](https://docs.coveo.com/en/1833#free-text-search)

* For more information on how to format values for this field, see [Catalog product data](https://docs.coveo.com/en/m53g7119/).

|`ec_price`  
(Required)
|Decimal
|The product's price.
|* Displays the product's price in the result template.

* Enabled field settings:

** [Facet](https://docs.coveo.com/en/1833#facet-and-multi-value-facet)[.footnote]^[[3](#generate-facets-1)]^

|`ec_item_group_id`  
(Required for [grouping](https://docs.coveo.com/en/l78i2152/))
|String
|An identifier used to group similar products together.
|* Enforces grouping of products in search results and product listing pages.

* Useful in [reports](https://docs.coveo.com/en/266/).

* Used by ML models.

* Enable the [required settings](https://docs.coveo.com/en/l78i2152#grouping-field-configuration) if you want pagination, [facet](https://docs.coveo.com/en/198/) counts, and result counts to reflect the number of groups rather than individual items.

|`ec_thumbnails`  
(Recommended)
|String
|A collection of lower resolution product images used for faster page load time (URL format).
|* Used in the result template to show the main product image.

|`ec_images`  
(Recommended)
|String
|A collection of high-resolution product images used to view product details (URL format).
|* Shows product images in the result template when high quality images are required.

|`ec_shortdesc`  
(Recommended)
|String
|A short description of the product.
|* Displays the product's short description in the result template.

|`ec_brand`  
(Recommended)
|String
|The product's brand.
|* Required for producing [product embeddings and vectors](https://docs.coveo.com/en/l9gg3565/).

* Displays the product's brand in the result template.

* Enabled field settings:

** [Facet](https://docs.coveo.com/en/1833#facet-and-multi-value-facet)[.footnote]^[[3](#generate-facets-1)]^

** [Free text search](https://docs.coveo.com/en/1833#free-text-search)

|`ec_cogs`  
(Recommended)
|Decimal
|Used to calculate the product margin.
|* Can be used to promote products with a higher margin.
|===

--
1. To improve [keyword](https://docs.coveo.com/en/2738/) relevance, **Name** and **Description** will be copied to **Title** and **Body** respectively by the default [Catalog source](https://docs.coveo.com/en/l5if0244/) [mappings](https://docs.coveo.com/en/217/).

2. Set `ec_product_id` as your unique product ID field when [creating your catalog configuration](https://docs.coveo.com/en/3139#catalog-configuration).

3. [facet](https://docs.coveo.com/en/198/) [fields](https://docs.coveo.com/en/200/) can be used to generate [product listing pages (PLPs)](https://docs.coveo.com/en/m1sf3187/).
--

**Deprecated standard commerce fields**
<details><summary>Details</summary>

The following standard commerce fields were deprecated in October 2025.
Although these fields remain supported, they no longer affect Coveo functionality, and are no longer automatically created in new Catalog sources.

[%header,cols="3,1,3,5a"]
|===
|Field
|Type
|Description
|Usage notes

|`ec_rating`
|Decimal
|A rating-based system from 0-10.
|* Displays the product's rating in the result template.

* Enabled field settings:

** [Facet](https://docs.coveo.com/en/1833#facet-and-multi-value-facet)[.footnote]^[[4](#generate-facets-2)]^

|`ec_in_stock`
|String
|Boolean indicating whether the product is in stock.
Valid values are `true` or `false`.
|* Indicates whether the product is in stock in the result template.

* The string value must be either `true` or `false`.

* Enabled field settings:

** [Facet](https://docs.coveo.com/en/1833#facet-and-multi-value-facet)[.footnote]^[[4](#generate-facets-2)]^

|`ec_promo_price`
|Decimal
|The product's promotional price.
|* Displays the product's promotional price in the result template.

* Enabled field settings:

** [Facet](https://docs.coveo.com/en/1833#facet-and-multi-value-facet)[.footnote]^[[4](#generate-facets-2)]^
|===

--
4. [facet](https://docs.coveo.com/en/198/) [fields](https://docs.coveo.com/en/200/) can be used to generate [product listing pages (PLPs)](https://docs.coveo.com/en/m1sf3187/).
--

</details>

> **Important**
>
> Avoid modifying the [metadata](https://docs.coveo.com/en/218/) of standard commerce fields using an [indexing pipeline extension (IPE)](https://docs.coveo.com/en/206/).
> This action can make the data unusable for internal systems, such as [Coveo Personalization-as-you-go](https://docs.coveo.com/en/m5kd0347/) [models](https://docs.coveo.com/en/1012/).

## Structure fields

In addition to the standard commerce [fields](https://docs.coveo.com/en/200/), you must add structure [fields](https://docs.coveo.com/en/200/) to set up your [catalog configuration](https://docs.coveo.com/en/l5if0520/).

You must manually create most of these fields in your [Coveo organization](https://docs.coveo.com/en/185/) if they don't already exist.
However, depending on your implementation, you might not need to create all of them.

Make sure to [create source mappings](https://docs.coveo.com/en/n8of7021#catalog-structure-fields-mapping-catalog-source) for these [fields](https://docs.coveo.com/en/200/).
If you're using a [Catalog source](https://docs.coveo.com/en/l5if0244/), these [source](https://docs.coveo.com/en/246/) [mappings](https://docs.coveo.com/en/217/) are automatically created.
For example, the `ec_availability_id` [field](https://docs.coveo.com/en/200/) is automatically mapped to the `ec_availability_id` [metadata](https://docs.coveo.com/en/218/) key.

The following table lists the catalog structure fields and their properties:

[%header,cols="1a,1,1a,1a,1a"]
|===
|Field
|Description
|Field setting options to enable
|Example
|Usage

|`objecttype`  
(String)
|Identifies the [item](https://docs.coveo.com/en/pa8f6515/)'s [catalog object](https://docs.coveo.com/en/ncig0154/) (product, variant, or availability).
|* [Facet](https://docs.coveo.com/en/1833#facet-and-multi-value-facet)
|`Availability`
|Mandatory for all commerce [items](https://docs.coveo.com/en/pa8f6515/) to define their [catalog object](https://docs.coveo.com/en/ncig0154/) type.

|`ec_variant_id`  
(String)
|Uniquely identifies each sellable [variant](https://docs.coveo.com/en/mc7f0326/) in a catalog entity with variants.
|* [Facet](https://docs.coveo.com/en/1833#facet-and-multi-value-facet)

* [Use cache for nested queries](https://docs.coveo.com/en/1833#use-cache-for-nested-queries)
|`887056_35F_24`
|Only create this field if your catalog entity contains [variants](https://docs.coveo.com/en/mc7f0326/).

|`ec_availability_id`  
(String)
|Uniquely identifies each [availability](https://docs.coveo.com/en/mc7e9096/) channel.
|* [Facet](https://docs.coveo.com/en/1833#facet-and-multi-value-facet)

* [Use cache for nested queries](https://docs.coveo.com/en/1833#use-cache-for-nested-queries)
|`s000002`
|Only create this field if your catalog entity contains [availability](https://docs.coveo.com/en/mc7e9096/) channels.

|`ec_available_items`  
(String)
|Identifies the list of available products and [variants](https://docs.coveo.com/en/mc7f0326/) in a given [availability](https://docs.coveo.com/en/mc7e9096/) channel.
|* [Multi-value facet](https://docs.coveo.com/en/1833#facet-and-multi-value-facet)

* [Use cache for nested queries](https://docs.coveo.com/en/1833#use-cache-for-nested-queries)
|`["887056_35F_24", "887056_35F_25", "887056_35F_26", "887056_35F_36", "887056_35F_38"]`
|Only create this field if your catalog entity contains [availability](https://docs.coveo.com/en/mc7e9096/) channels.
|===

## Create additional commerce fields

You can also add your own fields to provide users with additional information about your products.
These additional fields also [let users target their desired content](https://docs.coveo.com/en/1833#use-fields-in-a-search-interface).

You can [create your fields manually](https://docs.coveo.com/en/1833#add-a-field) through the [Administration Console](https://platform.cloud.coveo.com/login) ([platform-ca](https://platform-ca.cloud.coveo.com/login) | [platform-eu](https://platform-eu.cloud.coveo.com/login) | [platform-au](https://platform-au.cloud.coveo.com/login)), or programmatically through the [Fields API](https://platform.cloud.coveo.com/docs?urls.primaryName=Field#/Fields/rest_organizations_paramId_indexes_fields_batch_create_post).
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.

> **Tip**
>
> * You'll want to [explore your metadata](https://docs.coveo.com/en/m9ti0339/) before you create your fields.
> 
> * Ensure that your field has the same exact name as the product metadata indexed in your source.

If you don't use `ec_product_id` as your unique product identifier, you must create a field that matches the name of your metadata key.
You must also [map your unique product identifier to the `permanentid` field](https://docs.coveo.com/en/n8of7021#map-to-permanentid-catalog-source).

The mapping of your metadata has to be done through the source mappings.
See [Additional fields mapping](https://docs.coveo.com/en/n8of7021#custom-fields-mapping-catalog-source) for instructions on how to map your additional fields to your metadata.

> **Leading practice**
>
> In your catalog content, avoid using the same field name that you intend to use as [facets](https://docs.coveo.com/en/198/), on different types of items.
> For example, if you're defining the `color` at a product level, then you shouldn't define the `color` at the variant level.
> If you must include a field at both levels, prefix it with `product` and `variant` (e.g, `productcolor`, `variantcolor`) so that they're different in the index.

## Fields per `objecttype`

The fields defined in this article will be used for different [object types](https://docs.coveo.com/en/n8of5561/) in your source.

[%header,cols="3,1,1,1"]
|===
|Field
|Product
|Variant
|Availability

|`ec_name`
|[check]
|[check]
|[check]

|`ec_product_id`
|[check]
|[check]
|

|`ec_description`
|[check]
|
|

|`permanentid`
|[check]
|[check]
|[check]

|`ec_category`
|[check]
|
|

|`ec_item_group_id`
|[check]
|
|

|`ec_price`
|[check]
|
|

|`objecttype`
|[check]
|[check]
|[check]

|`documentid`
|[check]
|[check]
|[check]

|`ec_variant_id`
|
|[check]
|

|`ec_availability_id`
|
|
|[check]

|`ec_available_items`
|
|
|[check]

|`latitude`
|
|
|[check]

|`longitude`
|
|
|[check]
|===

## Payload example

When [sending your catalog data for indexing](https://docs.coveo.com/en/p48b0322/), ensure that the required standard commerce and structure fields are included in your payload.
You'll also want to include any recommended or optional fields that are relevant to your products, variants, or availabilities.

The following JSON snippet shows an example of products with variants and availabilities, including the required standard commerce and structure fields, as well as some recommended fields and additional custom fields:

```json
{
  "addOrUpdate": [ <1>
    {
      "documentId": "product://SP01020_002", <2>
      "ec_name": "Okeanos Kayak",
      "ec_description": "This sea kayak is perfect for beginner and experienced kayakers. It's lightweight, easy to assemble, and comfortable to use.",
      "ec_product_id": "SP01020_00002",
      "ec_category": "Canoes & Kayaks ; Canoes & Kayaks|Kayaks ; Canoes & Kayaks|Kayaks|Sea Kayaks",
      "ec_price": "2200.00",
      "ec_item_group_id": "SP01020",
      "ec_thumbnails": "https://images.barca.group/...",
      "ec_images": "https://images.barca.group/...",
      "ec_shortdesc": "This sea kayak is perfect for beginner and experienced kayakers.",
      "ec_brand": "Barca Sports",
      "ec_cogs": 0.54,
      "objecttype": "Product",
      "number_of_seats": 1,
      "material": "Polyethylene",
      "water_type": "Calm",
      "kayak_type": "Recreational",
      "kayak_size": "10 ft"
    },
    {
      "documentId": "variant://SP01020_002_blue", <3>
      "ec_name": "Okeanos Kayak - Blue",
      "ec_product_id": "SP01020_00002",
      "ec_variant_id": "SP01020_0002_blue",
      "objecttype": "Variant",
      "color": "Blue"
    },
    {
      "documentId": "availability://s000001", <4>
      "ec_name": "New York Store",
      "ec_availability_id": "s000001",
      "ec_available_items": [
        "SP01020_0002_blue",
        "SP01020_0002_red",
        // ...
      ],
      "objecttype": "Availability",
      "latitude": 40.71427,
      "longitude": -74.00597
    },
    // ...
  ]
}
```

<1> The `addOrUpdate` operation contains an array of items to be indexed through a Stream API request.

<2> A product item, containing:

[%header,cols="~,~a,~a"]
|===
|Required standard and structure fields
|Optional standard fields
|Custom fields

a|* `documentid`

* `ec_name`

* `ec_product_id`

* `ec_description`

* `ec_category`

* `ec_price`

* `ec_item_group_id`

* `objecttype`
|* `ec_thumbnails`

* `ec_images`

* `ec_shortdesc`

* `ec_brand`

* `ec_cogs`

|* `number_of_seats`

* `material`

* `water_type`

* `kayak_type`

* `kayak_size`
|===

<3> A variant item, containing:

[%header,cols="~,~a,~a"]
|===
|Required standard and structure fields
|Optional standard fields
|Custom fields

a|* `documentid`

* `ec_name`

* `ec_product_id`

* `ec_variant_id`

* `objecttype`
|
|* `color`
|===

<4> An availability item, containing:

[%header,cols="~,~a,~a"]
|===
|Required standard and structure fields
|Optional standard fields
|Custom fields

a|* `documentid`

* `ec_name`

* `ec_availability_id`

* `ec_available_items`

* `objecttype`
|
|* `latitude`

* `longitude`
|===

## What's next?

Once you've ensured that all the required [fields](https://docs.coveo.com/en/200/) exist in your [organization](https://docs.coveo.com/en/185/), you must define proper [mappings](https://docs.coveo.com/en/217/) between your product [metadata](https://docs.coveo.com/en/218/) and your [fields](https://docs.coveo.com/en/200/).

See [Map commerce fields](https://docs.coveo.com/en/n8of7021/) for more information.