Commerce 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.

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 commerce standard fields section for the exhaustive list of standard commerce fields.

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 (e.g., 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] (see facet field).

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] (see facet field).

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: Product brand
Usage:

Display name: Special Price
Type: Decimal
Description: Promotional price of product or variant
Usage:

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

  • Can be used to generate facets[2] (see facet field).

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] (see facet field).

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 a Product Listing Page (PLP).

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 using the following field names:

Notes
  • Your catalog data may employ different names to store the metadata that the catalog structure fields expect. For example, instead of productid, your equivalent catalog product identifier could be uniqueid. If this is the case, 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. Minimally, however, you’ll always have to configure a field that uniquely identifies products in your catalog.

objecttype

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

productid

Type: String
Description: Uniquely identifies each product within a single catalog source. This field is expected in the product and variant catalog object type, and commonly mapped to permanentid in the catalog source.
Enable these field setting options:

sku

Type: String
Description: Uniquely identifies each variant, unless no variants exist. When a product has no variants, the sku must be mapped to the permanentid.
Enable these field setting options:

availabilityid

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

availableskus

Type: String
Description: Identifies the list of available product 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 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.

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

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