Commerce fields
Commerce fields
Commerce fields hold key information about each item in your index. They contain metadata, such as the product name or price, that power your product discovery experiences with Coveo.
You can use these commerce fields to:
-
Provide specific information about each individual product, variant, or availability channel.
-
Enforce your product catalog structure.
-
Create facets to refine search results.
-
Make sure that Coveo Personalization-as-you-go (PAYG) models can leverage product embeddings and vectors.
-
Enrich Coveo Analytics events with the expected catalog data.
When preparing your catalog data for indexing, one of the first steps is to configure these fields.
This article explains which fields are required, recommended, and optional to set up in your Coveo for Commerce organization.
|
The resource snapshots feature lets you copy configurations from one Coveo for Commerce organization to another, such as when you migrate from a sandbox to a production organization. It only copies the source configuration, not the source content. Use this feature to reuse your catalog entities and their catalog configurations, your Catalog sources, and your fields and field mappings. |
Standard commerce fields
The standard commerce fields ensure that:
-
Coveo has the necessary data to drive its machine learning models.
-
Coveo Analytics events logged using the Event Protocol are enriched with the proper catalog data.
When you create a Catalog source in your Coveo organization, the standard commerce fields are automatically generated and can’t be changed. With other source types, you must create these fields yourself.
Make sure to create mappings for these fields.
You must also map the unique product identifier to the permanentid field.
|
Note
To train Coveo ML models, you can’t use the |
The following table lists the standard commerce fields and their properties:
| Field | Type | Description | Usage notes |
|---|---|---|---|
|
String |
The product’s name. |
|
|
String |
The product’s description. |
|
|
String |
The product’s unique identifier within a single source. |
|
|
String |
The product’s category. |
|
|
Decimal |
The product’s base price. |
|
|
String |
An identifier used to group similar products together. |
|
|
String |
A collection of lower resolution product images used for faster page load time (URL format). |
|
|
String |
A collection of high-resolution product images used to view product details (URL format). |
|
|
String |
Boolean indicating whether the product is in stock.
Valid values are |
|
|
String |
A short description of the product. |
|
|
String |
The product’s brand. |
|
|
Decimal |
The product’s promotional price. |
|
|
Decimal |
Used to calculate the product margin. |
|
|
Decimal |
A rating-based system from 0-10. |
1. To improve keyword relevance, Name and Description will be copied to Title and Body respectively by the default Catalog source mappings.
2. Set ec_product_id as your unique product ID field when creating your catalog configuration.
3. facet fields can be used to generate product listing pages (PLPs).
|
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. |
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 add these fields yourself.
Make sure to create source mappings for these fields.
If you’re using a Catalog source, these source mappings are automatically created.
For example, the ec_availability_id field is automatically created and mapped to the ec_availability_id metadata key.
The following table lists the catalog structure fields and their properties:
| Field | Description | Field setting options to enable | Example |
|---|---|---|---|
|
Identifies the item's catalog object (product, variant, or availability). |
|
|
|
Uniquely identifies each sellable variant in a catalog entity with variants. |
|
|
|
Uniquely identifies each availability channel. |
|
|
|
Identifies the list of available products and variants in a given availability channel. |
|
|
|
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. |
Create additional commerce fields
You can also add your own fields to provide users with additional information about your products. These additional fields also let users target their desired content.
You can create your fields manually through the Administration Console (platform-ca | platform-eu | platform-au), or programmatically through the Fields API. Fields are also used as attributes to build rules in the Coveo Merchandising Hub (CMH). If you want to use a given field as an attribute in rules, you must enable the Facet or Multi-value facet option for that field.
|
|
|
If you don’t use ec_product_id as your unique product identifier, you must create a field that matches the name of your metadata key.
You must also map your unique product identifier 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.
|
|
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 |
Fields per objecttype
The fields defined in this article will be used for different object types in your source.
| Field | Product | Variant | Availability |
|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
||
|
|
|
|
|
|
||
|
|
||
|
|
||
|
|
|
|
|
|
|
|
|
|
||
|
|
||
|
|
||
|
|
||
|
|
Payload example
When sending your catalog data for indexing, ensure that the required standard commerce and structure fields are included in your payload. You’ll also want to include any recommended or optional fields that are relevant to your products, variants, or availabilities.
The following JSON snippet shows an example of products with variants and availabilities, including the required standard commerce and structure fields, as well as some recommended fields and additional custom fields:
{
"addOrUpdate": [ 
{
"documentId": "product://SP01020_002", 
"ec_name": "Okeanos Kayak",
"ec_description": "This sea kayak is perfect for beginner and experienced kayakers. It's lightweight, easy to assemble, and comfortable to use.",
"ec_product_id": "SP01020_00002",
"ec_category": "Canoes & Kayaks ; Canoes & Kayaks|Kayaks ; Canoes & Kayaks|Kayaks|Sea Kayaks",
"ec_price": "2200.00",
"ec_item_group_id": "SP01020",
"ec_thumbnails": "https://images.barca.group/...",
"ec_images": "https://images.barca.group/...",
"ec_in_stock": true,
"ec_shortdesc": "This sea kayak is perfect for beginner and experienced kayakers.",
"ec_brand": "Barca Sports",
"ec_promo_price": 2200.00,
"ec_cogs": 0.54,
"ec_rating": 3,
"objecttype": "Product",
"number_of_seats": 1,
"material": "Polyethylene",
"water_type": "Calm",
"kayak_type": "Recreational",
"kayak_size": "10 ft"
},
{
"documentId": "variant://SP01020_002_blue", 
"ec_name": "Okeanos Kayak - Blue",
"ec_product_id": "SP01020_00002",
"ec_variant_id": "SP01020_0002_blue",
"objecttype": "Variant",
"color": "Blue"
},
{
"documentId": "availability://s000001", 
"ec_name": "New York Store",
"ec_availability_id": "s000001",
"ec_available_items": [
"SP01020_0002_blue",
"SP01020_0002_red",
// ...
],
"objecttype": "Availability",
"latitude": 40.71427,
"longitude": -74.00597
},
// ...
]
} |
The addOrUpdate operation contains an array of items to be indexed through a Stream API request. |
||||||
|
A product item, containing:
|
||||||
|
A variant item, containing:
|
||||||
|
An availability item, containing:
|
What’s next?
Once you’ve ensured that all the required fields exist in your organization, you must define proper mappings between your product metadata and your fields.
See Map commerce fields for more information.
Very useful
Not really
Very useful
Not really