Create recommendation configurations

This is for:

Developer

You must create a recommendation slot configuration before you can fetch Product Recommendations (PR) from the Commerce API.

Recommendation slot configurations define the recommendation strategies and the locations within your storefront where the recommendation slots will be used.

There are two types of configurations: global and specific.

  • Global configuration: Define shared configuration that you want to apply to all recommendations slots, such as additional fields and the number of recommendations per page.

  • Specific configuration: Define a configuration for each recommendation slot on your website to configure the Commerce API to return only products that match a certain recommendation strategy.

You can create or modify your recommendation configurations in two ways:

  1. Through the Coveo Merchandising Hub

  2. Using the configuration endpoints directly (which the CMH uses under the hood)

Note

While the Coveo Merchandising Hub (CMH) provides an easy way to create or modify individual recommendation slots, interacting with the configuration endpoint is useful for batch-creating or modifying slots because you can script these calls.

Additionally, at this time, the CMH doesn’t let you configure the additional fields that should be returned with your query or modify the global configuration. To do this, call the configuration endpoints directly.

Recommendation slots

A recommendation slot is a specific area within a storefront where product recommendations are displayed. It can be configured to determine where and how recommendations will appear to users.

When creating a recommendation slot, you must define the location of the slot within your storefront, the type of products used to generate recommendations, and the recommendation strategy to use. This can be done by setting the slotType, seedType, and strategy parameters in the recommendation slot configuration.

Configuring the recommendation slot

The recommendation strategy used by a slot depends on several parameters that you must configure:

  1. The slotType for your recommendation slot. This determines the location of the recommendation slot in your storefront. It also determines which seedType can be used.

  2. The seedType specifies the type of products used to generate recommendations. Seed types include:

    • unseeded: Recommendations are based on the user’s overall behavior, not on any particular product.

    • Seeded: In addition to the user’s behavior, recommendations are based on a specific product or set of products. There are three types of seeded recommendations:

      • product: Recommendations are based on a single particular product.

      • cart: Recommendations are based on items in the user’s cart.

      • purchased: Recommendations are based on the user’s purchase history.

    The seedType also determines which strategy can be used.

    To understand which slot types support which seed types, see Supported seed types by slot type.

  3. The strategy parameter specifies which recommendation algorithm to use, based on the seedType. Several strategies are available:

    • popular_bought - recommends the most purchased products.

    • popular_viewed - recommends the most viewed products.

    • cart - recommends other products that were frequently purchased together in previous similar carts.

    • viewed_together - recommends products that are frequently viewed together with one or more products provided as seeds.

    • bought_together - recommends products that are frequently bought together with one or more products provided as seeds.

    • buy_again - recommends products that the user has purchased in the past.

    • session_recommender_single_seed - an intent-aware recommendation strategy based on a visitor’s real-time actions and the product they’re viewing.

    To understand which seed types support which strategies, see Supported strategies by seed type.

Supported seed types by slot type

The following table shows the supported seed types for each slot type.

Slot type Supported seed types

home

unseeded

cart

listing

unseeded

cart

search

unseeded

cart

productDetail

unseeded

product

cart

cart

unseeded

cart

confirmation

unseeded

cart

purchased

global

unseeded

product

cart

purchased

Supported strategies by seed type

The following table shows the supported strategies for each seed type.

Seed type Strategies

unseeded

popular_viewed

popular_bought

buy_again

product

all unseeded strategies

viewed_together

bought_together

session_recommender_single_seed (Intent-aware)

cart

all unseeded strategies

cart

viewed_together

bought_together

purchased

all unseeded strategies

viewed_together

bought_together

Manage recommendations using the Coveo Merchandising Hub

The Coveo Merchandising Hub (CMH) allows merchandisers to manually curate the products displayed in recommendation slots.

While Coveo ML models provide intelligent and personalized recommendations, the CMH allows you to manually adjust them to meet your business needs.

For example, merchandisers can use the CMH to:

  • Promote specific products when certain products are viewed.

  • Boost or bury products on recommendations based on specific criteria.

To learn more about the CMH and how to use it, see Coveo Merchandising Hub (CMH).

Manage recommendations using the configuration endpoints

A recommendation slot configuration is a JSON object that follows a specific format. You can modify it by calling the configuration endpoints and providing a configuration JSON.

Global recommendation configuration

A global configuration defines shared settings that apply to all recommendation slots in your storefront.

This configuration is useful for setting parameters such as:

  • perPage: The number of recommended products to return per slot.

  • additionalFields: The additional product fields to return in the API response, such as ec_material, ec_brand, or custom labels.

Call the /commerce/v2/recommendations/slots/global/query-configuration endpoint to set the global configuration.

Here is a sample global configuration JSON:

{
  "additionalFields": [
    "ec_material"
  ],
  "perPage": 10
}

Specific recommendation configuration

Call the /commerce/v2/recommendations/slots endpoint to create a recommendation slot.

Here is a sample configuration JSON for a recommendation slot that appears on the cart page:

{
    "name": "Cart Recs", 1
    "trackingId": "sports", 2
    "slotType": "cart", 3
    "seedType": "cart", 4
    "strategy": "bought_together", 5
    "headlines": [ 6
        {
            "headline": "Customers also bought",
            "language": "en"
        }
    ],
    "minRecs": 5,
    "queryConfiguration": { 7
        "additionalFields": [
            "color",
            "shirtsize"
        ],
        "perPage": 10
    }
}
1 The name of the recommendation slot configuration. This is what appears in the CMH.
2 The trackingId allows you to segregate your configurations.
3 The slotType helps merchandisers determine where the recommendation slot lives on the storefront.
4 The seedType determines which type of data will be used to generate recommendations and which strategies can be used.

For example, if you set the seed type to cart, the recommendations will be based on the items present in the user’s cart. In this case, the only strategies that can be used are bought_together or viewed_together.
5 The strategy parameter specifies which recommendation algorithm to use within the context defined by the seedType. strategy can be changed over time depending on the merchandiser’s needs, without altering the seedType.
6 The headline to display in the recommendation slot.
7 The query configuration to use for the recommendation slot.

In this example, additional fields are specified to be returned by the query, and the number of recommendations per page is set to 10.