Map commerce fields

This is for:

Developer

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

Once you’ve created the required fields, you must ensure proper mapping between the metadata available in the items you indexed in your source and the fields.

Note

While you don’t need to manually create standard commerce fields when using a Catalog source, you must properly map them to ensure these fields are populated with the correct metadata.

Standard commerce fields mapping

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

While the best practice when structuring your product, variant, and availability data is to use the same field names as the standard commerce fields (prexixed with ec, for example, ec_price), your catalog data may use other names to store the information that the standard fields expect to receive (for example, price).

In such case, you must map this information to the standard fields that were automatically created in your Coveo organization. The Manage source mappings article 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"
 }

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, you create mapping rules to map the brand and price metadata to the ec_brand and ec_price standard fields.

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.

Note that the mapping done in this section isn’t replicated at the source level. Rather, it lets PAYG models target and learn from the right content.

In the Associated Metadata section, use the metadata name used after the mapping process. For example, if in your product data, the price of a product is stored with the price key, but you then applied a mapping rule to map the price metadata to the ec_price field, you must enter ec_price in the Associated Metadata field.

Note

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

Structure fields mapping

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

While the best practice when structuring your product, variant, and availability data is to use the same field names as the recommended field names (for example, productid), your catalog data may use other names to store the information that the structure fields expect to receive (for example, 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.

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.