Create additional commerce fields

Coveo organization sources offer a set of default system fields. However, adding your own fields will provide end users with additional information when search results are returned. It also lets them better target their desired content (see Field uses).


Default fields won’t be available in the field picker of the Coveo Administration Console.

The mapping of your metadata has to be done through the source mappings. You will want to explore your metadata before you create your fields.


Ensure your field has the same exact name as the product metadata created within Coveo.

For example, if you want to map your metadata my_price, then the field my_price needs to be created in Coveo before creating the source mapping.

You can create your fields manually through the Administration Console (platform-eu | platform-au), or programmatically through the Fields API.

Leading practice

In your catalog content, avoid using the same field name that you intend to use as facets, 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 need to include a field at both levels, prefix it with product and variant (e.g, productcolor, variantcolor) so that they’re different in the index.

Commerce field name suggestions

In addition to the fields you will want to create to leverage product metadata such as price, color, and description within your commerce interfaces (search and listing pages, recommendation interfaces, etc.), you must create a set of string type fields that you will use to configure your Coveo commerce catalog:

Suggested field name Field intent Field settings to enable


Uniquely identifies each product.

check Facet

check Use cache for nested queries


Uniquely identifies each variant.


Uniquely identifies each availability channel.


Identifies the list of available product/variants in a given availability channel.

check Multi-value Facet

check Use cache for nested queries

If your catalog only contains products that don’t have variants, or if the products in your catalog are offered through a single availability channel (e.g., a single store or product list), you won’t need to configure all of the fields listed in the previous table. Minimally, however, you will always have to configure a field that can uniquely identify products in your catalog.


When your catalog structure contains large amounts of items and requires availability channels, use the same field name (i.e. availableskus) on both the variant objecttype

  "DocumentId": "variant://001-red-8_wide",
  "FileExtension": ".html",
  "ec_name": "Coveo Soccer Shoes - Red / Size 8 - Wide",
  "sku": "001-red-8_wide",
  "availableskus": ["001-red-8_wide"],
  "productsize": "8",
  "width": "wide",
  "productid": "001-red",
  "objecttype": "Variant"

and availability channel objecttype written in an array.

  "DocumentId": "store://montreal",
  "FileExtension": ".html",
  "ec_name": "Montreal Store",
  "availableskus": ["001-red-8_wide", "001-red-7-narrow", "..."],
  "objecttype": "Availability"

This will improve the performance of your index.