Commerce fields

This is for:

Developer

In this article

Standard commerce fields
Create additional commerce fields
Commerce structure fields

A field is an index-wide data container that holds specific information about each individual item whose corresponding source mappings include rules to populate this field.

Each Coveo organization automatically comes with a set of default fields populated using standard metadata. You can also create custom fields that are filled with the content or metadata of your choice when adding mappings for sources (see Add or edit a field). Fields can be leveraged in a search interface to optimize the user experience by displaying relevant information about your products and providing facet options.

Standard commerce fields

To ensure optimal performance of your Coveo for Commerce implementation, it’s essential to populate the Coveo for Commerce standard fields. These commerce-related fields store vital metadata on your products, such as price, name, and description.

The purpose for having a standardized set of product data is so that you can map product information with user data for Coveo Machine Learning models. As a result, models can enhance content personalization for your customers.

The word standard is important here, as these fields are the same across all Coveo organizations and expect similar values to be stored in them. To get a holistic view of fields that aren’t specific to commerce, see About fields.

When you create a Catalog source, standard fields are automatically generated in your Coveo organization. You can access them by navigating to the Fields (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console. Standard commerce-related fields are prefixed with ec_ (e.g., ec_price). These fields need to be populated with relevant product metadata through source mappings and during the catalog creation process. See Standard commerce fields mapping for more information on how to map these fields. See the list of all standard fields section for the exhaustive list of standard commerce fields.

Standard fields reference

Note

The standard fields listed as "High" importance in the table are the most critical ones.

Display name Index field name Importance Description Format

Display name	Index field name	Importance	Description	Format
Name^[1]	`ec_name`	High	Name of the product	String
Description^[1]	`ec_description`	High	Description of the product	String
Brand	`ec_brand`	High	Product brand	String
Category	`ec_category`	High	Category of the product (e.g., Electronics; Electronics\|Televisions; Electronics\|Televisions\|4K Televisions)	String
Price	`ec_price`	High	Base price of the product or variant	Float
Item Group ID	`ec_item_group_id`	High	For product grouping or bundling	String
Short Description	`ec_shortdesc`	Low	Short description of the product	String
Image	`ec_thumbnails`	Low	Lower resolution product image(s) used for faster page load time (URL format)	Array
Images Gallery	`ec_images`	Low	Collection of high resolution product images used to view product details (URL format)	Array
Special Price	`ec_promo_price`	Low	Promotional price of product or variant	Float
In Stock	`ec_in_stock`	Low	Availability of the product (i.e., whether the product is in stock)	Boolean
COGS	`ec_cogs`	Low	To calculate the product margin	Float
Ratings	`ec_rating`	Low	A rating based system from 0-10	String

Name^[1]

ec_name

High

Name of the product

String

Description^[1]

ec_description

High

Description of the product

String

Brand

ec_brand

High

Product brand

String

Create additional commerce fields

You can also add your own fields to provide end users with additional information from your products. These additional fields also let users target their desired content (see Field uses).

The mapping of your metadata has to be done through the source mappings. See Additional fields mapping for instructions on how to map your additional fields to your metadata.

You will want to explore your metadata before you create your fields.
Ensure your field has the same exact name as the product metadata indexed in your source.

You can create your fields manually through the Administration Console (platform-ca | 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 structure fields

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

Suggested field name	Field intent	Field settings to enable
`productid`	Uniquely identifies each product.	Facet Use cache for nested queries
`sku`	Uniquely identifies each variant.
`availabilityid`	Uniquely identifies each availability channel.
`availableskus`	Identifies the list of available product/variants in a given availability channel.	Multi-value Facet Use cache for nested queries

productid

Uniquely identifies each product.

Facet

Use cache for nested queries

sku

Uniquely identifies each variant.

availabilityid

Uniquely identifies each availability channel.

availableskus

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

Multi-value Facet

Use cache for nested queries

Note that you must ensure that these fields are mapped to the appropriate metadata in your source. See Structure fields mapping for instructions on how to map your structure fields to your metadata.

If your catalog only has 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 the fields listed in the table. Minimally, however, you will always have to configure a field that uniquely identifies products in your catalog.

If your catalog structure contains many items and requires availability channels, use the same field name on both the variant and the availability channel to store the SKU array. The JSON object below demonstrates this by using the availableskus field:

{
  "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"
}

{
  "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.

1. Name and Description will be copied to Title and Body respectively by the Catalog source default mappings to improve keyword relevance.