Commerce catalog

This is for:

System Administrator

The Coveo commerce catalog is the core structure of Coveo for Commerce. It defines the structure of commerce-related items in your index. In other words, it establishes relationships between a set of items representing catalog products, variants, and availability channels within the sources that contain your catalog content. The commerce catalog also lets you standardize your data to enable the proper use of Coveo Machine Learning models.

Creating a commerce catalog is a requirement for enabling product embeddings and vectors, using the Stream API, and analyzing usage analytics data through advanced commerce reporting.

In a commerce-enabled Coveo organization, members with the required privileges can use the Catalogs (platform-ca | platform-eu | platform-au) page to initially create catalogs, and come back anytime to manage them.

Prerequisites

Before creating a commerce catalog, ensure you have at least one source in your Coveo organization (see Add or edit a source). The source used must be a Catalog source, or a source that has the Coveo Personalization-as-you-go feature enabled. See Enable Coveo Personalization as you go (PAYG) for more information.

Add a catalog

  1. On the Catalogs (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console, click Add Catalog. This will open the Add a Catalog panel.

  2. Enter a suitable Name for your catalog (for example, acme-full-catalog).

    This name appears in the catalog list of the Catalogs page. It can also be used to reference the catalog when querying its content from a search interface.

  3. (Optional) In the Description field, enter a suitable description for your catalog (for example, The various products and services offered by the ACME Corporation).

  4. Under Object Types, select the catalog objects your catalog should include:

    • If the source you want to use only contains catalog product data objects without Variant or Availability catalog objects, continue to step 5.

      Example

      The following table shows products that don’t use the Variant catalog object to define different variations of a product.

      The color variations of the Lazer Headphones products are indexed as individual products and use the product catalog object instead.

      Product Product ID

      Red Lazer Headphones

      0001

      Blue Lazer Headphones

      0002

      Notes
      • By default, your products are available from a unique distribution channel unless the Availability option is selected.

      • You can’t change the Object Types for the items in your catalog once they have been created.

    • If your catalog data contains items of the variant catalog object to handle different variations of a product (for example, color or size), select Variants.

      Example

      The following tables show the structure of a product-variants relationship for the Coveo Soccer Shoes - Red product.

      Product Product ID

      Coveo Soccer Shoes - Red

      0001

      Variant Product ID Variant ID

      Coveo Soccer Shoes - Red - Size 8

      0001

      SKU0001

      Coveo Soccer Shoes - Red - Size 9

      0001

      SKU0002

    • If your catalog data contains items of the availability catalog object to control whether a product or variant is available in a specific channel (for example, a store or a warehouse), select the Availability checkbox.

      Example

      The following table shows a catalog structure in which certain products or variants are available in specific stores:

      Channel Available product IDs or variant IDs

      Québec Store

      0001, 0002

      London Store

      0001

  5. Under Catalog Content, select the source that contains your catalog data objects. The source you select can only be used with a single catalog.

    Note

    The source selection will affect the following:

    • The scope of the catalog preview, once your catalog is created.

    • The scope of the selectable configuration dropdown menus (or available fields within dropdown menus).

    • The facet association.

  6. Depending on the way you’ve structured your data, your availability data might be in another source. In this case, from the dropdown menu, select that source. Otherwise, clear the Use a different source for availabilities checkbox.

  7. To continue selecting a configuration for your catalog, click Next.

    Note

    If you need to change the catalog structure, you’ll need to create a new catalog. For example, your commerce catalog only had items of the Product catalog object, and now you want to add variants or availability channels.

Catalog configuration

A catalog configuration is a reusable structure of commerce-related items in your index that can be applied to many catalogs, which allows you to re-use the structure across many brands or stores. It establishes relationships between a set of catalog object types representing products, variants, and availability channels as well as standard fields mapping.

When configuring a commerce catalog, you can either select an existing catalog configuration or create a new one.

Use an existing catalog configuration

  1. Select a previously created configuration.

  2. Click Finish. The catalog is now available on the Catalogs (platform-ca | platform-eu | platform-au) page.

  3. Once you selected the catalog configuration to use for the commerce catalog, you must stream your catalog data into the source once more. This ensures that the catalog is properly registered and ensures the proper functioning of Coveo ML models.

Tip

If you have the Enterprise edition, group this catalog and your other implementation resources together in a project. See Manage projects.

Create a new catalog configuration

  1. Click Create a New Configuration.

  2. Enter a suitable Configuration name as you may need to return and use it later, and then click Next to provide information about the products you want to include your catalog.

Example

Let’s say you want to use the same configuration for two catalogs. Your catalogs are language specific ACME EN and ACME FR. You would want to distinguish the actual structure of the configuration from the specializations, therefore you could name your configuration ACME default configuration.

Products
  1. Under Define your products, select the objecttype field value that identifies items as products in your index (for example, Product).

  2. Under Select your Product ID field, select the field that uniquely identifies each distinct product (for example, ec_product_id). If there are no variants available, you can advance to associating your metadata with Coveo’s standard fields by clicking Next. Otherwise, continue to variants.

    Notes
    • Ensure that the selected field has the Facet and Use cache for nested queries settings enabled.

    • If the catalog hierarchy has variants, the value of the Product ID field must link each variant to its parent product. Select a field whose value is the same for any given product and all its associated variants.

    • If your catalog hierarchy has no variants, but many availability channels, the Product ID field must link each product to the availability channel it’s available in.

Variants
Important

If your catalog configuration contains variants, it’s essential to ensure that all products in that catalog have at least one associated variant, even if the product itself doesn’t come in different variations.

In cases where a product has no variations, you must create a variant with minimal information to prevent this variant from appearing as a filtering option for the attached product.

See Variants for products that have no variations to learn how to configure a variant object for a product that has no variations.

  1. Under Define your variants, select the objecttype field value that identifies items as variants in your index (for example, Variant).

  2. Under Select your Product SKU field, select the field that uniquely identifies each distinct variant (for example, sku).

    Notes
    • Ensure that the selected field has the Facet and Use cache for nested queries settings enabled.

    • If your catalog hierarchy has many availability channels, the value of the Product SKU field links each variant to the availability channels it’s available in. Select a field whose value is also contained in items of the availability catalog object in which this variant is available.

  3. To add field values for your availabilities, click Next.

Availabilities
  1. Under Define your availabilities, select the objecttype field value that identifies items as availability channels in your index (for example, Availability).

  2. Under Select your Availability ID field, select the field to use to uniquely identify each availability channel in your index (for example, availabilityid)

    Note

    Ensure that the selected field has the Facet and Use cache for nested queries settings enabled.

  3. Under Select your Available SKUs field, select the multi-value field that lists all sellable items (product or variants) available from each distinct availability channel (for example, availableskus).

    Notes
    • Ensure that the selected field has the Multi-value facet and Use cache for nested queries settings enabled.

    • If your catalog hierarchy has variants, the chosen field should contain one or more variant IDs (for example, sku). Otherwise, it should contain one or more product IDs.

    • The visible tabs and sections depend on the catalog object structure and availability structure you selected when you created your catalog.

    • To allow a user to query the catalog without an availability filter, returning all results, see Disable availability filtering.

  4. Click Next.

Commerce standard fields

In the Map standard fields to your catalog step of the catalog configuration, you’ll be asked to map standard commerce fields to metadata from your index. This is to make sure that Coveo Personalization-as-you-go (PAYG) can build a product vector space that represents your content.

If you haven’t pushed your commerce data to your source yet, you wouldn’t be able to see your metadata keys in the dropdowns of the Associated Metadata column. However, if you know the nomenclature of the metadata keys you’ll be using, you can write them in the Associated Metadata column.

Continuing with the example of pricing, here you would need to map the price metadata key to the ec_price field.

Warning

This step isn’t to be confused with regular source mapping where you map metadata from your source to Coveo fields. See Map commerce fields for details.

  1. In the Associated Metadata column, select the metadata to associate to the ec_ field(s).

  2. Click Finish. The catalog is now available on the Catalogs (platform-ca | platform-eu | platform-au) page. Note that if you’re using a Catalog source to index your commerce data, the mapping you’re doing here will be replicated in the source’s mapping.

  3. Once your commerce catalog is created, stream your catalog data into the source once more. This ensures that the catalog is properly registered and ensures the proper functioning of Coveo ML models.

Tip

If you have the Enterprise edition, group this catalog and your other implementation resources together in a project. See Manage projects.

Edit a commerce catalog

You can edit a commerce catalog to change its name, the source it uses, the catalog configuration it’s associated with, or the associated facets.

"Overview" tab

  1. On the Catalogs (platform-ca | platform-eu | platform-au) page, click the desired catalog, and then click Edit in the Action bar. This will open the Overview tab.

  2. Edit the Name for your catalog (for example, acme-full-catalog).

    This name appears in the catalog list in the Administration Console. It can also be used to reference the catalog when querying its content from a search interface.

  3. In the Catalog Content dropdown menu, you can change the source that contains your product’s metadata. The source you select can only be used with a single catalog.

    Note

    The source selection will affect the following:

    • The scope of the catalog preview, once your catalog is edited.

    • The scope of the selectable configuration dropdown menus (or available fields within dropdown menus).

    • The facet association.

  4. If your catalog has availability objects and the way you’ve structured your data has changed, your availability data might now be contained in another source. In this case, select the new source from the dropdown menu. Otherwise, clear the Use a different source for availabilities checkbox.

    Refer to Leverage variants and availabilities for more information.

  5. Click Save.

  6. When you’re done editing your commerce catalog, you must stream your catalog data into the source once more. This ensures that the catalog is properly registered and ensures the proper functioning of Coveo ML models.

"Facet Association" tab

The Facet Association tab lets you quickly view which facetable field names exist for each catalog object. The percentage shown represents the ratio of each field by catalog object type. By hovering over the percentage shown, you can see the number of documents that contain the associated field name.

Note

Depending on your specific use case, if the percentages deviate from what you expect, this could be an indication that your data isn’t properly structured.

In advanced use cases, your data structure may require having the same facetable fields on multiple catalog object types. For example, you may want to use the same language field across all your items. In this case, the value @language would need to appear on all catalog objects (Product, Variant, and Availability) to return matching results.

To access the Facet Association tab:

  1. On the Catalogs (platform-ca | platform-eu | platform-au) page, click the catalog used by your search interface, and then click Edit in the Action bar.

  2. Select the Facet Association tab.

  3. Select the desired field, and then click Edit Field on the Action bar.

    You’ll be sent to the Content > Fields page. You can edit the string options or advanced settings. For more information, see Add or edit a field.

  4. Click Save.

  5. When you’re done editing your commerce catalog, you must stream your catalog data into the source once more. This ensures that the catalog is properly registered and ensures the proper functioning of Coveo ML models.

  6. (Optionally) Click Refresh Field Cache in the upper-right corner.

    This allows you to instantly update the field values you edited instead of waiting for them to update automatically through the staged refresh, which automatically detects the fields that you can use to generate facets every 15 minutes. The last update time appears at the lower right of the Facet Association tab in your catalog.

Delete a commerce catalog

On the Catalogs (platform-ca | platform-eu | platform-au) page, click the desired catalog, and then click Delete in the Action bar.

Manage commerce catalog configurations

Depending on the structure you’ve created for your commerce environment, you may need to change or delete your configurations. For example, if you need to redefine which objecttype field value identifies as a product in your index.

Edit a commerce catalog configuration

Warning
WARNING

Editing a configuration will impact all associated catalogs.

  1. On the Catalogs (platform-ca | platform-eu | platform-au) page, click Manage Configurations.

  2. Click Edit configuration icon to edit the configuration.

For more information on how to configure a catalog configuration, refer to the Catalog configuration section.

Delete a commerce catalog configuration

Note

You can’t delete a catalog configuration without first deleting the associated catalog(s). Once the associated catalog is deleted, the previously associated configuration will remain in your Manage configurations interface until it’s manually deleted.

  1. On the Catalogs (platform-ca | platform-eu | platform-au) page, click Manage Configurations.

  2. Click Delete configuration icon next to the configuration you want to delete.

What’s next?

Once you’ve completed your catalog configuration, you must associate your catalog with the target tracking ID and locale (see Storefront associations).

Required privileges

The following table indicates the privileges required for your organizations groups to view or edit elements of the Catalogs (platform-ca | platform-eu | platform-au) page and associated panels (see Manage privileges and Privilege reference). The Commerce domain is, however, only available in Coveo commerce organizations.

Action Service - Domain Required access level

View catalogs

Commerce - Catalogs
Content - Sources
Content - Fields
Organization - Organization

View

Edit catalogs

Content - Fields
Content - Sources
Organization - Organization

View

Commerce - Catalogs

Edit

Search - Execute Query

Allowed