Commerce fields

This is for:

Developer System Administrator

When preparing your catalog data for indexing, one of the first steps is to configure the commerce fields that hold key information about each item. These fields contain metadata, such as the product name or price, that power your product discovery experiences with Coveo.

This article explains which fields are required, recommended, and optional to set up your Coveo for Commerce organization.

Standard commerce fields

Standard fields are used by machine learning models and other key functionalities, such as usage analytics event tracking.

When you create a Catalog source, the standard commerce fields are automatically generated in your Coveo organization, and can’t be changed. With other source types, you must create these fields yourself, as per the following table.

Field Type Description Usage notes

ec_name[1]

(Required)

String

The product’s name.

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

  • Enabled field settings:

ec_description[1]

(Required)

String

The product’s description.

ec_product_id

(Required)

String

The product’s unique identifier within a single source.

ec_category

(Required)

Array[String]

The product’s category.

ec_price

(Required)

Decimal

The product’s base price.

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

  • Enabled field settings:

ec_item_group_id

(Required for grouping)

String

An identifier used to group similar products together.

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

  • Useful in reports

  • Used by ML models

ec_thumbnails

(Recommended)

String

A collection of lower resolution product images used for faster page load time (URL format).

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

ec_images

(Recommended)

String

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

ec_in_stock

(Recommended)

String

Whether the product is in stock.

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

  • Enabled field settings:

ec_shortdesc

(Recommended)

String

A short description of the product.

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

ec_brand

(Recommended)

String

The product’s brand.

ec_promo_price

(Recommended)

Decimal

The product’s promotional price.

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

  • Enabled field settings:

ec_cogs

(Recommended)

Decimal

Used to calculate the product margin.

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

ec_rating

(Recommended)

Decimal

A rating-based system from 0-10.

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

  • Enabled field settings:

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

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

An item payload where the metadata keys match the standard fields:

{
  "AddOrUpdate": [
    {
     "ec_name": "Graysuit",
     "ec_description": "This Gray Acrylic pants for …​",
     "ec_product_id": "SP04968_00004",
     "ec_category": "Clothing ; Clothing|Pants ; Clothing|Pants|Acrylic",
     "ec_price": "154",
     "ec_item_group_id": "SP04968",
     "ec_thumbnails": "https://images.barca.group/...",
     "ec_images": "https://images.barca.group/...",
     "ec_in_stock": true,
     "ec_shortdesc": "This Gray Acrylic pants for …​",
     "ec_brand": "North Face",
     "ec_promo_price": 139.00,
     "ec_cogs": 0.54,
     "ec_rating": 3,
     // ...
   },
   // ...
  ]
}

There are two levels of mappings to consider to ensure that you correctly populate your standard commerce fields:

  1. Source mappings

    • If you’re using a Catalog source, the standard fields and their source mappings are automatically created (for example, the ec_name field is automatically created and mapped to the ec_name metadata key). You only need to create source mappings if you’re not using a Catalog source or for item custom metadata keys, if you use any. See Map commerce fields: With a Catalog source.

    • If you’re not using a Catalog source, you must define source metadata mappings. See Standard commerce fields catalog mapping.

  2. Catalog configuration mappings

    Configure your Commerce standard field mappings during the catalog entity creation process.

Map permanentid

The permanentid field should hold the same value as the product’s unique identifier.

When using a Catalog source and the ec_product_id metadata key for your product’s unique identifier, the value of the ec_product_id field is automatically mapped to the permanentid field.

However, if you use a different metadata key for your product’s unique identifier, or if you don’t use a Catalog source, you must manually map the unique product identifier to the permanentid field. Additionally, you must create a custom field that matches the name of your chosen metadata key exactly. For example, if the metadata key that uniquely identifies a product is product_code, you must create a field named product_code in Coveo and map it to the permanentId field.

Notes

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

  • Set ec_product_id as your unique product ID field when creating your catalog configuration.

Structure fields

In addition to the standard commerce fields, structure fields are required for setting up your catalog configuration.

When you create a Catalog source, the catalog structure fields are automatically created in your organization. With other source types, you must create these fields yourself, as per the following table.

Field Description Field setting options to enable Example

objecttype

(String)

Identifies the item's catalog object (product, variant, or availability).

Availability

ec_variant_id

(String)

Uniquely identifies each sellable variant in a catalog entity with variants.

887056_35F_24

ec_availability_id

(String)

Uniquely identifies each availability channel.

s000002

ec_available_items

(String)

Identifies the list of available products and variants in a given availability channel.

["887056_35F_24", "887056_35F_25", "887056_35F_26", "887056_35F_36", "887056_35F_38"]
Note

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

Make sure to create source mappings for those fields. If you’re using a Catalog source, the standard fields and their source mappings are automatically created. For example, the ec_availability_id field is automatically created and mapped to the ec_availability_id metadata key.

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.

If you’re not using the ec_product_id metadata key for your product’s unique identifier, you must create a field that matches the name of your chosen metadata key exactly and map it to the permanentId field. For example, if the metadata key that uniquely identifies a product is product_code, you must create a field named product_code in Coveo and map it to the permanentId field.

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.

Fields per objecttype

The fields defined in this article will be used for different object types in your source.

Field Product Variant Availability

ec_name

check

check

check

ec_product_id

check

check

ec_decription

check

permanentid

check

check

check

ec_category

check

ec_item_group_id

check

objecttype

check

check

check

documentid

check

check

check

ec_variant_id

check

ec_availability_id

check

ec_available_items

check

latitude

check

longitude

check

What’s next?

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

See Map commerce fields for more information.