Create recommendation configurations

This is for:

Developer

You need to 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.

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

The CMH lets you modify recommendation strategies and view performance metrics for your recommendation slots. However, it doesn’t currently support creating new recommendation slots or setting specific rules to filter and rank products. This functionality is coming soon.

For now, to create new recommendation slots or set rules to filter and rank your products, you’ll have to 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 need to 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 need to 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.

Here is a sample configuration for a recommendation slot that lives 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.