Catalog product data

This is for:

Developer

Products are searchable items. In a catalog entity without variants, products are also purchasable items.

In a catalog entity that contains variants, customers will purchase variant items, which represent specific sellable versions of the products. However, if your catalog entity exclusively includes items of the product catalog object, customers will purchase product items, not variants. See Catalog variant data and product groupings to learn more about variants.

Here’s an example of a JSON representation of a product named Coveo Soccer Shoes - Red, which includes generic information such as its description, image, and price.

{
  "documentId": "product://001-red", 
  "FileExtension": ".html",
  "ec_name": "Coveo Soccer Shoes - Red",
  "model": "Authentic",
  "ec_brand": ["Coveo"],
  "ec_description": "<p>The astonishing, the original, and always relevant Coveo style.</p>",
  "color": ["Red"],
  "ec_item_group_id": "001",
  "ec_product_id": "001-red", 
  "ec_images": ["https://myimagegallery?productid"],
  "gender": "Men",
  "price_dict": { 
      "": "28.00",
      "store1": "28.00",
      "store2": "30.00"
  },
  "ec_category": [ 
    "Shoes",
    "Shoes|Soccer shoes",
    "Shoes|Sport shoes|Soccer shoes"
  ]
  "objecttype": "Product" 
}

The value of the documentId metadata is the unique identifier of your item in the index and will also serve as the item’s uri field value. This value must be a valid URL with a proper URI prefix, such as product://, or any other scheme that fits your catalog data. The URL format ensures that the documentId is recognized as a valid URI, which is essential for updating the item’s information in the index.

ec_product_id is the unique identifier of your product. Depending on your catalog configuration, this metadata may have a different label.

Note

To train Coveo Machine Learning (Coveo ML) models, this metadata can’t contain the # character.

The price_dict is a dictionary field that can be used in an environment where products need to have different prices (for example, when the price is based on location or seasonal pricing) for a single item, instead of sending a single price value (see Dictionary fields).

Note

If your product’s price is static, you can store the product’s price in a single price field (for example, ec_price).

The ec_category metadata is used to define the categories and hierarchical structure of your products. This field can represent multiple categories, separated by ;, as well as category hierarchies, separated by |.

Two formats are supported:

An array of strings (recommended), where you use | to separate different levels within each category hierarchy.

{
  // ...
  "ec_category": [
    "Shoes",
    "Shoes|Soccer shoes",
    "Shoes|Sport shoes|Soccer shoes"
  ]
  // ...
}

String format, where you use ; to separate categories and | to separate different levels within each category hierarchy.

Note

While this format is still supported, it’s recommended to use an array of strings for clarity and future compatibility.
```
{
  // ...
"ec_category": "Shoes ; Shoes|Soccer shoes ; Shoes|Sport shoes|Soccer shoes"
  //  ...
}
```

The objecttype metadata is crucial, as it will be used to identify the item as a product in the index.

When defining your product data, we highly recommend using the standard fields for storing related data (for example, using ec-prefixed fields, such as ec_price). This will simplify the mapping process later on.

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.