Recombee Docs
Visit recombee.comStart Free
docs20User Documentation
adminuiAdmin UI
codeAPI Clients & Integrations
cookhatScenario Recipes


Scenario defines a particular application of recommendations at your website, your mobile app or emailing campaign. It can be for example homepage, watch-next, cart or emailing-after-purchase.

You can set different behavior of the recommendations for each scenario and then monitor the performance of the scenarios in the KPI section.

Setting up a Scenario#

  1. Create scenario in the Admin UI

    • Go to the Scenarios section and click Create scenario.
    • You need to set a name of the scenario and choose the recommendation endpoint which will be used in the scenario.
    Create scenario
  2. Set scenario parameter in the recommendation requests or create a HTML Widget

    In case of using the API:

    • Pass the name of the created scenario to scenario parameter of the recommendation request
    • Example for scenario homepage:
client.send(new recombee.RecommendItemsToUser(userId, count,
		scenario: 'homepage',
), callback);
result = client.send(RecommendItemsToUser(user_id, count,
result = client.send(, count,
	'scenario' => 'homepage'
RecommendationResponse  result = client.send(
	new RecommendItemsToUser(userId, count).setScenario("homepage")
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.RecommendItemsToUser(userId, count,
	'scenario': 'homepage'
), callback);
$result = $client->send(new RecommendItemsToUser($user_id, $count,
	'scenario' => 'homepage'
RecommendationResponse result = client.Send(
		RecommendItemsToUser(userId, count, scenario: "homepage")
GET /{databaseId}/recomms/users/userId/items/?count=10&scenario=homepage

Not sure which scenarios will work the best in your use case? See the Integration Tips.

Scenario settings in the Admin UI#

You can customize each of your scenarios.

Setting Logic & Filter in the Admin UI
Setting Logic & Filter in the Admin UI#


Logic specifies the desired behavior of the recommendation model.

Setting Logic in the Admin UI

If you want to change the Logic in Admin UI, but logic parameter is already sent in the API requests and you are not a programmer, you can enable Override logic API parameter to use your settings from Admin UI.


Filters allow you to specify which items can be recommended in this scenario. You can pick some rules from Recombee library or your own Business Rules.

An item can be recommended only as long as all the filter rules applied to the scenario are satisfied.

Set filter

If you specify a filter as API parameter of the recommendation request, the filters from Admin UI will be combined with the filer specified in the request using the AND operator.


Boosters allow you to prefer some items in this scenario in order to fulfill your business goals. You can pick some rules from Recombee library or your own Business Rules.

Each booster rule produces a number when evaluated for an item. The final boosting score for an item is computed as product of these scores from individual booster rules.

Set booster

If you specify a booster as API parameter of the recommendation request, the boosters from Admin UI will be combined with the filer specified in the request using the * operator.


Constraints allow you to configure how items with shared conditions may repeat within the recommendation results.

For example, you may want to recommend:

  • At most 2 items from each category
  • or at most 50 % of items from a single genre
  • or just a single product per a parent product ID

In order to do that, you first need to create an Item Segmentation that describes the shared condition. This may be as simple as choosing one of the item properties - e.g. the category, however, it also enables you to express much more advanced rules.

When you have the Item Segmentation ready, you can add the Constraint to your Scenario and choose how many items per individual Segment (particular category, genre, etc.) can appear in the recommendation result.

Constraints in Admin UI

Limit type#

  • Absolute: Sets the maximal number of items from a single Segment in the returned recommendations
    • e.g. at most 3 items from a single brand
  • Percentage: Sets the maximal portion of returned recommendations that comprise of items from a single Segment
    • e.g. at most 25 % from a single brand

Window size#

In the case of the Absolute limit type, the given maximum count of items per Segment is by default applied to all the recommended items.

However, you may apply it only to smaller parts of the results by setting the window size.

For example, if you set the maximum count of items per Segment to 2 and the window size to 4, then within each consecutive 4 items in the recommendations at most 2 can be from a single Segment.

Global Settings#

If you want to apply some Filters or Boosters to all of your Scenarios, you can put them to Global Settings - for example, you may always want to filter out the items that are not currently available.

By putting rules to Global Settings you ensure that these rules are always applied and you don’t need to worry about forgetting them when adding a new Scenario.

This Filter rule is applied to all Scenarios
This Filter rule is applied to all Scenarios#

Business Rules#

Recombee Library#

There is a Recombee library of generally useful filter and booster rules that can be applied to your scenarios. You can for example allow only items in stock or items from a particular category to be recommended, or boost recent items.

Custom Rules#

Beside these out-of-the-box rules, you can define your completely custom rules using our flexible ReQL language.

You can also let our AI ReQL Code Assistent generate the rule for you, based on your natural language input.

For example you can create a filter rule that allows only short (<30 minutes) movies in English to be recommended:

Creating own Business Rule

If you have multiple scenarios, and you want to recommend movies of a different length in each of them, you can make the maximal runtime an input value - parameter of the rule.

Adding Input value
Adding Input value

When you then apply this rule to a scenario, you can specify the maximal allowed runtime in minutes:

Applying own Business Rule to a Scenario

Check also the ReQL documentation and tutorial.

HTML Widget#

The Admin UI allows you to create a HTML Widget for each of your Scenarios in order to display the recommendations at your website.

See this Getting Started section for more info about the HTML Widgets.

Setting a HTML Widget in the Admin UI
Setting a HTML Widget in the Admin UI#
© Copyright 2024, Recombee s.r.o