Map commerce fields

This is for:

Developer System Administrator

Coveo for Commerce implementations require the use and creation of specific index fields.

The Commerce fields article provides an exhaustive list of the standard fields that must be used, along with information on how to leverage commerce catalog structure fields and creating your own custom fields.

These commerce fields are essential to the proper functioning of the Coveo for Commerce solution. They let you:

Standard commerce fields catalog mapping

When configuring your commerce catalog, the Standard fields section lets you map the standard commerce fields to the metadata available in your source. This procedure lets PAYG models target and learn from the right content.

Depending on the source you use to index your product inventory, note that the mapping done in this section isn’t always replicated at the source level. See Standard commerce fields mapping for details.

Note

Don’t forget to stream your catalog data into the source whenever you apply changes to the Standard field section.

Standard commerce fields source mapping

Mapping requirements are different depending on the type of source you use to index your product inventory:

With a Catalog source

When creating a Catalog source, your Coveo organization automatically creates the required standard commerce fields for you.

When structuring your product, variant, and availability data, it’s recommended to use the same field names as the standard commerce fields (prefixed with ec, e.g., ec_price).

However, your catalog data may use different names to store information that the standard fields expect (e.g., price).

In such case, you can use the standard commerce fields catalog mapping of the catalog configuration to map the standard commerce fields to the metadata available in your source. This mapping will be replicated at the source level.

Example

You uploaded the following product data to your Catalog source:

 {
   "documentId": "product://001-red",
   "FileExtension": ".html",
   "ec_name": "Coveo Soccer Shoes - Red",
   "model": "Authentic",
   "brand": ["Coveo"],
   "ec_description": "<p>The astonishing, the original, and always relevant Coveo style.</p>",
   "color": ["Red"],
   "ec_item_group_id": "001",
   "productid": "001-red",
   "ec_images": ["https://myimagegallery?productid"],
   "gender": "Men",
   "price": "30",
   "ec_category": "Soccer Shoes",
   "objecttype": "Product"
 }

While some product data is stored with the keys that match the created standard fields (ec_name, ec_description, ec_item_group_id, ec_images, ec_category), other data that must fill the standard fields is stored with different keys (brand and price).

Therefore, when mapping standard fields to your catalog, you map the brand and price metadata to the ec_brand and ec_price standard fields.

With a cloud source

When using a SAP, Salesforce, Database, GraphQL API, or REST API source, you must manually map the metadata to the standard commerce fields. As opposed to Catalog sources, this is required even if you already mapped the metadata to the standard fields in the catalog configuration.

The Manage source mappings article provides all the information you need to define the proper mappings rules.

Structure fields mapping

To structure your Coveo commerce catalog, you must create a set of fields that uniquely identify the items in your source.

When structuring your product, variant, and availability data, it’s advisable to use the same field names as the recommended field names (e.g., productid). However, your catalog data may employ different names to store the information that the structure fields expect (e.g., uniqueid).

You must ensure that these fields are mapped with corresponding metadata from the items in your source.

Example

As recommended in the Commerce structure fields section, you created the following fields to enforce your catalog structure:

  • productid

  • sku

  • availabilityid

  • availableskus

In your catalog data, the metadata that must fill these fields is stored with different keys. For example, the unique identifier of each product is stored with the uniqueid key.

Therefore, you create a mapping rule that maps the uniqueid metadata to the productid field.

Important

When using a SAP, Salesforce, Database, GraphQL API, or REST API source, you must manually map the metadata that uniquely identifies the items in your source to the permanentId field.

Additional fields mapping

In addition to the standard commerce fields, you may want to map other metadata to fields that you created in your Coveo organization.

For example, it’s likely that you created fields to store additional metadata that are relevant to the products you’re selling, such as color, size, gender, or model.

In this case, you must create mapping rules to map the metadata to the fields that you created in your Coveo organization. The Manage source mappings provides all the information you need to define the proper mappings rules for your Catalog source.

Example

You uploaded the following product data to your Catalog source:

 {
   "documentId": "product://001-red",
   "FileExtension": ".html",
   "ec_name": "Coveo Soccer Shoes - Red",
   "model": "Authentic",
   "brand": ["Coveo"],
   "ec_description": "<p>The astonishing, the original, and always relevant Coveo style.</p>",
   "color": ["Red"],
   "ec_item_group_id": "001",
   "productid": "001-red",
   "ec_images": ["https://myimagegallery?productid"],
   "gender": "Men",
   "price": "30",
   "ec_category": "Soccer Shoes",
   "objecttype": "Product"
 }

In your Coveo organization, you created the following fields to store additional metadata about your products:

  • product_color

  • product_gender

  • product_model

Therefore, you create mapping rules to map the color, gender, and model metadata to the product_color, product_gender, and product_model fields.