Commerce fields

This is for:

In this article

Standard commerce fields
Commerce structure fields
Create additional commerce fields
What’s next?

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.

Standardizing product data enables you to map product information with user data for Coveo Machine Learning models, enhancing content personalization for your customers.

The word standard is important here, as these fields are the same across all Coveo for Commerce 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_ (for example, 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

This table lists all the standard commerce fields that are automatically created when you create a Catalog source in your Coveo organization, as well as their level of importance and usage. The index field name and format of standard fields created in your organization, as well as any additional fields you create, can’t be changed.

Display name Index field name Format Importance Description Usage

Display name	Index field name	Format	Importance	Description	Usage
Name^[1]	`ec_name`	String	Required	Name of the product	Displays the product’s title in the result template
Free text searchable
Description^[1]	`ec_description`	String	Required	Description of the product	Required for producing product embeddings and vectors
Displays the product’s description in the result template
Free text searchable
Category	`ec_category`	String	Required	Category of the product (for example: `Electronics; Electronics\|Televisions; Electronics\|Televisions\|4K Televisions`) See Catalog product data for more information on how to structure your categories.	Required for producing product embeddings and vectors
Displays the product’s category in the result template
Can be used to generate facets^[2] (see facet field)
Free text searchable
Price	`ec_price`	Float	Required	Base price of the product or variant	Displays the product’s price in the result template
Can be used to generate facets^[2] (see facet field)
Item Group ID	`ec_item_group_id`	String	Required (see Product grouping)	Groups similar products together	Enforces grouping of products in search results and product listing pages
Image	`ec_thumbnails`	Array	Required	Lower resolution product image(s) used for faster page load time (URL format)	Used in the product’s result template to show the main product image
Images Gallery	`ec_images`	Array	Required	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
In Stock	`ec_in_stock`	Boolean	Required (when leveraging availabilities)	Availability of the product (that is, whether the product is in stock)	Indicates whether the product is in stock in the product’s result template
Can be used to generate facets^[2] (see facet field)
Short Description	`ec_shortdesc`	String	Recommended	Short description of the product	Displays the product’s short description in the result template
Brand	`ec_brand`	String	Recommended	Product brand	Required for producing product embeddings and vectors
Displays the product’s brand in the result template
Can be used to generate facets^[2] (see facet field)
Free text searchable
Special Price	`ec_promo_price`	Float	Recommended	Promotional price of product or variant	Displays the product’s promotional price in the result template
Can be used to generate facets^[2] (see facet field)
COGS	`ec_cogs`	Float	Recommended	To calculate the product margin	Can be used to promote products with a higher margin
Ratings	`ec_rating`	String	Recommended	A rating based system from 0-10	Displays the product’s rating in the result template
Can be used to generate facets^[2] (see facet field)

Name^[1]

ec_name

String

Required

Name of the product

Displays the product’s title in the result template

Free text searchable

Description^[1]

ec_description

String

Required

Description of the product

Required for producing product embeddings and vectors

Displays the product’s description in the result template

Free text searchable

Commerce structure fields

In addition to the standard fields that were created in your organization, you must create a set of identifier fields that you’ll use to configure your Coveo commerce catalog:

Note

All the identifier fields listed below are required to be of the String data type.

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 (for example, a single store or product list), you won’t need to configure all the fields listed in the table. Minimally, however, you’ll always have to configure a field that uniquely identifies products in your catalog.

If an item of the availability catalog object has more than 1,000 skus listed in the availableskus field, we recommend that the related items (product or variant) also contain the availableskus field.

The value must be formatted as an array, but contain only one item, which is the sku of the item, as shown in the following code samples. This will improve the performance of your index.

Availability:

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

Related variant:

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

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’ll 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.

What’s next?

Once you’ve ensured that all the required fields exist in your Coveo organization, you must define proper mapping between your product metadata and your fields.

See Map commerce fields for more information.

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

2. Facet fields can be used to generate Product Listing Page (PLP).