Manage commerce catalogs
Manage commerce catalogs
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 areProduct
,Variant
, orAvailability
.See Catalog objects for more information about the
objecttype
field.
Add a catalog
-
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.
-
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.
-
(Optional) In the Description field, enter a suitable description for your catalog (for example,
The various products and services offered by the ACME Corporation
). -
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
orAvailability
object types, continue to step 7.ExampleThe 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.ExampleThe 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.ExampleThe 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
-
-
Under Catalog Content, select the source that contains your catalog data. The source you select can only be used with a single catalog.
NoteThe 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.
-
-
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.
-
To continue with selecting a configuration for your catalog, click Next.
NoteIf 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
-
Select a previously created configuration.
-
Click Finish. The catalog is now available on the Catalogs (platform-ca | platform-eu | platform-au) page.
-
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
-
Click Create a New Configuration.
-
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.
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
|
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. |
-
Under Define your products, select the
objecttype
field value that identifies items as products in your index (for example,Product
). -
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
|
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. |
-
Under Define your variants, select the
objecttype
field value that identifies items as variants in your index (for example,Variant
). -
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.
-
-
To add field values for your availabilities, click Next.
Availabilities
-
Under Define your availabilities, select the
objecttype
field value that identifies items as availability channels in your index (for example,Availability
). -
Under Select your Availability ID field, select the field to use to uniquely identify each availability channel in your index (for example,
availabilityid
)NoteEnsure that the selected field has the Facet and Use cache for nested queries settings enabled.
-
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.
-
-
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. |
-
In the Associated Metadata column, select the metadata to associate to the
ec_
field(s). -
Click Finish. The catalog is now available on the Catalogs (platform-ca | platform-eu | platform-au) page.
-
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
-
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.
-
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.
-
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.
NoteThe 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.
-
-
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.
-
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.
-
-
Click Save.
-
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:
-
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.
-
Select API key for search or API key for analytics.
-
Click Create Key.
|
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. |
API key for search
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
Editing a configuration will impact all associated catalogs. |
-
On the Catalogs (platform-ca | platform-eu | platform-au) page, click Manage Configurations.
-
Click
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. |
-
On the Catalogs (platform-ca | platform-eu | platform-au) page, click Manage Configurations.
-
Click
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 |
View |
Edit catalogs |
Content - Fields |
View |
Commerce - Catalogs |
Edit |
|
Search - Execute Query |
Allowed |