Manage commerce catalogs

This is for:

Developer

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 your associated Catalog sources. The commerce catalog also lets you standardize your data to enable the proper use of Coveo Machine Learning models.

Furthermore, the creation of a commerce catalog is a requirement for product embeddings and vectors and for 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.

Note

You can also create catalogs using the Catalog API.

Prerequisites

Before creating a commerce catalog, ensure you have:

  • At least one source in your Coveo organization (see Add or edit a source).

  • Items containing value for the objecttype field.

    The values you can assign for the objecttype field are Product, Variant, or Availability.

    See Catalog objects for more information about the objecttype field.

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 Catalog source you want to use doesn’t contain any items of the Variant or Availability object types, continue to step 7.

      Example

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

      The color variations of the Lazer Headphones products are indexed as individual products and use the product object type 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 object type to handle different variations of a product (for example, color or size), select Variants.

      Example

      The following table shows the structure of a product-variants relationship for the Lazer Headphones product.

      Product Product ID

      Lazer Headphones

      0001
      Variant Product ID Variant ID

      Red Lazer Headphones

      0001

      SKU0001

      Blue Lazer Headphones

      0001

      SKU0002

    • If your catalog data contains items of the availability object type 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. 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 have structured your data, your availability data might be in another source, in that case, from the dropdown menu, select that source. Otherwise, clear the Use a different source for availabilities checkbox.

  7. To continue with 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 object type, 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 items representing catalog products, variants, and availability channels as well as the 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.

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
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 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, productid). 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 object type 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 object type 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.

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 existing metadata from your index. Continuing with the example of pricing, here you would need to map ec_price to your previously created field my_price. For more information on standard fields, see Commerce field names.

Note

To ensure the proper functioning of standard fields, they will need to be defined carefully and this starts with a good definition of Coveo fields. Once all your Coveo fields are created and populated by your metadata with the same name, you’ll be able to proceed with standard field mapping. For more information on how to create fields and map them properly to your metadata, see Commerce field names.

  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.

  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.

Edit a catalog

  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 (e.g., 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 have structured your data has changed, your availability data might now be contained in another source. In that 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. On the top of the page, select the Facet Association tab to quickly view which facetable field names exist for each object type.

    • Select the desired field, and then click Edit Field on the Action bar. For more information, see Add or edit a field.

    • (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 occurs after every 15 minutes.

  6. Click Save.

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

Create an API key

After you’ve created your catalog, you must create access tokens, such as API keys, to allow search interfaces to query your catalog content and send appropriate usage analytics data.

To create an API key:

  1. On the Catalogs (platform-ca | platform-eu | platform-au) page, click the catalog for which you want to create an API key, and then click Create API Key in the Action bar.

  2. Select API key for search or API key for analytics.

  3. Click Create Key.

Important

To modify an API key created from the Create API key option of the Action bar, such as for enforcing a search hub value, you must access the API Keys (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console.

See Manage API keys for more details.

Endpoints must be authenticated with either a search token or the API key for search you created for your catalog. This will let you retrieve results for search pages, product listings, or recommendations. For more information, see API key for search.

API key for analytics

This is specifically to create a key for analytics tracking. Upon receipt of a commerce event in Coveo Usage Analytics (Coveo UA), Coveo extracts the catalog ID for that event based on the API key. The collected events are then sent to Coveo Machine Learning (Coveo ML) models which help harmonize the results returned to the customers. For more information, see User authentication.

Manage 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 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 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 have completed your catalog configuration, you must associate your catalog to the query pipeline that handles end-user queries on your commerce search page (see Query your commerce catalog content).

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