Commerce fields

This is for:

Developer System Administrator

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.

Every Coveo organization automatically comes with a set of default fields which are populated using standard metadata. In a Catalog source, these default fields include a set of standard commerce fields and a product ID field. You can also create custom fields that are filled with the content or metadata of your choice when adding mappings for sources.

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 the 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 lets you 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 catalog mapping for more information on how to map these fields. See the list of all standard commerce fields section for the exhaustive list of standard commerce fields.

Important

Avoid modifying the metadata of standard commerce fields using an indexing pipeline extension (IPE). This action can make the data unusable for internal systems, such as Coveo Personalization-as-you-go models.

Make sure the metadata in these fields is accurate and up-to-date before indexing it in your Coveo organization.

Standard commerce fields reference

Some commerce fields are automatically created when you create a Catalog source in your Coveo organization.

Note

The index field name and format of commerce fields that are automatically created in your organization, as well as any additional fields you create, can’t be changed.

ec_name (Required)

Display name: Name[1]
Type: String
Description: The product’s name.
Usage:

ec_description (Required)

Display name: Description[1]
Type: String
Description: Product description.
Usage:

ec_category (Required)

Display name: Category
Type: String
Description: Category of the product.
For example, Electronics; Electronics|Televisions; Electronics|Televisions|4K Televisions.
See more on Catalog product data.
Usage:

ec_price (Required)

Display name: Price
Type: Decimal
Description: Base price of the product or variant.
Usage:

  • Displays the product’s price in the result template.

  • Can be used to generate facets.[2]

ec_item_group_id (Required)

Display name: Item Group ID
Type: String
Description: Groups similar products together.
Usage:

  • Enforces grouping of products in search results and product listing pages.

ec_thumbnails (Required)

Display name: Image
Type: String (Single value or array of strings)
Description: Lower resolution product image(s) used for faster page load time (URL format).
Usage:

  • Used in the product’s result template to show the main product image.

ec_images (Required)

Display name: Images Gallery
Type: String (Single value or array of strings)
Description: Collection of high resolution product images used to view product details (URL format).
Usage:

  • Shows product images in the result template when high quality images are required.

ec_in_stock (Required)

Display name: In Stock
Type: String
Description: Whether the product is in stock.
Usage:

  • Indicates whether the product is in stock in the product’s result template.

  • Can be used to generate facets.[2]

Display name: Short Description
Type: String
Description: Short description of the product.
Usage:

  • Displays the product’s short description in the result template.

Display name: Brand
Type: String
Description: The product’s brand.
Usage:

Display name: Special Price
Type: Decimal
Description: The promotional price of the product or variant.
Usage:

  • Displays the product’s promotional price in the result template.

  • Can be used to generate facets.[2]

Display name: COGS
Type: Decimal
Description: To calculate the product margin.
Usage:

  • Can be used to promote products with a higher margin.

Display name: Ratings
Type: Decimal
Description: A rating-based system from 0-10.
Usage:

  • Displays the product’s rating in the result template.

  • Can be used to generate facets.[2]

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 pages (PLPs).

Define a unique product identifier

You must have a field that uniquely identifies products in your Coveo commerce catalog. When you create a Catalog source, the ec_product_id field is automatically generated to serve this purpose.

The following mappings are critical to ensure that interactions are correctly attributed and that Coveo ML models work properly:

  • If the name of the catalog metadata matches the name of the field you use as the unique product identifier in your Catalog source, it will be mapped automatically. If not, then you must manually map the metadata to the unique product identifier field in the Catalog source.

  • You must map the unique product identifier to the permanentid field in the Catalog source.

Important

To train Coveo ML models, you can’t use the # character in the unique product identifier or permanentid fields.

In a catalog with no variants, you could instead use the sku structure field as your unique product identifier. You could even use a custom field, such as uniqueid.

Example

You use sku as the key for your product identifier in your catalog metadata, and you want to use the ec_product_id field as the unique product identifier in your Catalog source.

You must manually map the metadata to the ec_product_id field in the Catalog source.

ec_product_id

Type: String
Description: Uniquely identifies each product within a single Catalog source. This field is automatically created in the product and variant catalog object types.
Enable these field setting options:

Notes

  • ec_product_id must be mapped to permanentid in the Catalog source.

  • To train Coveo ML models, you can’t use the # character in the ec_product_id or permanentid fields.

Commerce catalog structure fields

In addition to the standard commerce fields that are created in your organization, you must create a set of fields that you’ll use to structure and configure your Coveo commerce catalog. We recommend that you use the following field names.

Notes

  • Your catalog data may use different names to store the metadata that the catalog structure fields expect. For example, instead of sku, your catalog variant identifier could be variantid. If this is the case, you must ensure that these fields are mapped to the appropriate metadata in your source. See Catalog structure fields mapping for instructions on how to map your catalog structure fields to your metadata.

  • If your catalog contains products without variants, or if the products in your catalog are offered through a single availability channel (for example, products are offered through a single store or product list), you won’t need to configure all of the fields listed in this section.

objecttype

Type: String
Description: Identifies the item's catalog object (product, variant, or availability).
Enable these field setting options:

sku

Type: String
Description: Uniquely identifies each sellable product. In a catalog with no variants, this is equivalent to the unique product identifier, and the two can be used interchangeably. However, in a catalog with variants, this field uniquely identifies each variant instead of each product.
Enable these field setting options:

Notes

  • In a catalog with no variants, if you use sku to uniquely identify each product, you must map this field to permanentid in the Catalog source.

  • To train Coveo ML models, you can’t use the # character in the unique product identifier or permanentid fields.

availabilityid

Type: String
Description: Uniquely identifies each availability channel.
Enable these field setting options:

availableskus

Type: String
Description: Identifies the list of available products and variants in a given availability channel.
Enable these field setting options:

Create additional commerce fields

You can also add your own fields to provide users with additional information from your products. These additional fields also let users target their desired content.

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.

Tip

  • You’ll want to explore your metadata before you create your fields.

  • Ensure that 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.

Tip
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 of 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.