Build a recommendation scheme

Build your recommendation scheme from the Content tab of Recommendations Studio by adding one or more recommendation blocks.

Recommendation blocks appear on the right side of the Content tab. Select a block to view and configure its settings. You can drag and drop blocks to reorder them, and clone or delete blocks from the block menu.

Each block has five configuration sections that you work through top to bottom:

Inputs → Item Exclusions → Item Filters → Additional Restrictions → Output

Add a recommendation block

Each recommendation block provides product recommendations based on a recipe. Select from the Blueshift recipe library as the base for the block, then refine the settings to match your requirements.

1. Click NEW BLOCK.
2. Select a recipe.
3. Click SELECT RECIPE. The new block appears on the right side of the Content tab.
4. Select the block from the right-side panel to open its settings, then configure its Inputs, Item Exclusions, Item Filters, Additional Restrictions, and Output settings.
5. Click SAVE to save your changes.

Inputs

The Inputs section changes dynamically based on the recipe you selected. Different recipes use different input layouts. The sections below describe the most common patterns you may see.

Event-based inputs

In recipes driven by user activity (such as views, purchases, or add-to-cart events), the Inputs section displays an event timeline with the following fields.

Click + Event to add additional event rows. To remove an event row, click the trash icon (🗑) next to it.

Some event-based recipes also include a Form input text field (at the top of the section) and a Form checkbox (at the bottom). The Form input defines the variable name for form data passed into the block. When the Form checkbox is checked, the block accepts input values from that form data. These are relevant when recommendations are triggered by form submissions or API requests.

Attribute-based inputs

In recipes that match items to a specific user or catalog attribute, the Inputs section displays an attribute selector. The field name varies by recipe. Some recipes also include a ranking selector to control how matched items are sorted.

Item list inputs

In recipes for manually curated recommendations, the Inputs section displays a List of Items separated by a delimiter text field where you enter item identifiers, and a Delimiter String field to define the separator (for example, a comma).

Item exclusions

Exclude items from recommendations based on user activity or messaging history.

Event exclusions

Exclude items based on event activity in the past 366 days. For example, exclude items a user has already purchased by adding a checkout event exclusion.

Configure the Event Name, time window (From Past, To Past, Time Unit), and Item reference. The Item dropdown lets you select an Item in Event or Parent Item, to exclude both, add a separate row for each. The system displays a computed date range so you can verify the exclusion window. Click + Event to add additional exclusion rules, or click the trash icon (🗑) to remove a rule.

Messaging exclusions

Exclude items based on messaging activity in the past 31 days. Click + Messaging Event to add a messaging exclusion rule.

After adding a rule, the Min number of previous messages field appears. This sets the threshold for how many times a specific item can be recommended to the same user within the time window. For example, if set to 2, the same item cannot be recommended to a user more than 2 times in the last X days.

Item filters

Use item attribute filters to control which items are included or excluded from the recommendation results. Filters are organized into three groups:

• MATCHES ALL OF THESE — Items must match every filter in this group. Use this to limit results to a specific category or attribute.
• MATCHES ANY OF THESE — Items must match at least one filter. Use this to include items from multiple brands or categories.
• MATCHES NONE OF THESE — Items matching any filter in this group are excluded. Use this to eliminate specific items by SKU, title, or other attributes.

For each filter, select the Item Attribute Name, an Operator, and the Item Attribute Value. Click + Item Filter to add filters within a group.

Filter using values from user or product attributes

Select the Filter using values from user/product attributes checkbox to compare item attributes against user or product attributes dynamically. When enabled, the filter value is not a static value you enter manually; instead, it is resolved at runtime from the user profile or the product catalog.

For example, you can filter recommended items to match the user's preferred brand, or compare one product attribute against another.

Additional restrictions

The Additional Restrictions section controls item availability and uniqueness within the block. When your scheme has multiple blocks, this section also includes de-duplication controls across blocks.

Output

Output settings determine how recommended items are ranked and how many items the block returns.

Recommendations based on the parent product

Parent items let you organize catalogs with hierarchical relationships—such as shows with seasons and episodes, or base products with color variants. Using parent items, you can recommend at the parent level rather than at the individual variant level.

For example, if a customer watches episodes from a comedy series, you can recommend other comedy series (parent items) rather than the next episode of the same series. Similarly, a retailer with many color variants of the same base item can recommend the base product.

Parent items apply in three areas of the recommendation block:

• In Inputs — Change the Item dropdown from Item in Event to Parent Item so the parent item of the event item is considered. To consider both the item and its parent, add a separate event row for each.
• In Event-based exclusions — Change the Item dropdown to Parent Item to exclude parent items. To exclude both the item and its parent, add a separate exclusion row for each.
• In Output — Check the Parent Items checkbox in the Output section. The parent items of the final results are recommended in the block.

Handle empty recommendations

When Fail if empty is checked on a block, messaging is suppressed for users if the block returns no items. The recommendation is not executed, and an error code is sent to prevent the message from being sent.

Use this in conjunction with the Do not message users if any of the recommendation blocks are empty option in your messaging template. Combining both settings gives you precise control over when messages are sent.

Example: How settings affect message delivery

Consider the following scenario to understand how the selected options affect message delivery.

User Jane Smith qualifies for Campaign A with an email trigger that uses Template Y. Template Y uses Recommendation Scheme X with two recommendation blocks, B1 and B2.

The outcome depends on three settings: whether Fail if empty is checked on each block, and whether Do not message users if any of the recommendation blocks are empty is enabled on the template. The following six combinations cover all permutations, each showing four product availability scenarios (both blocks have items, only B1 has items, only B2 has items, neither has items).

Combination 1: Fail if empty = On or Off (both blocks), Template suppression = On. The template suppresses the message whenever either block is empty, regardless of the Fail if empty setting on individual blocks.

Combination 2: Fail if empty = Off (both blocks), Template suppression = Off. No suppression is configured, so the message is always sent regardless of product availability in either block.

Combination 3: Fail if empty = On (B1), Off (B2), Template suppression = Off. Only B1's emptiness is caught. The message is suppressed when B1 is empty but still sent when only B2 is empty.

Combination 4: Fail if empty = Off (B1), On (B2), Template suppression = Off. Only B2's emptiness is caught. The message is suppressed when B2 is empty but still sent when only B1 is empty.

Combination 5: Fail if empty = On (both blocks), Template suppression = Off. Fail if empty alone is sufficient to suppress the message when either block is empty — template suppression is not required.

Combination 6: Fail if empty = On (B1), Off (B2), Template suppression = On. B1's emptiness is caught by Fail if empty. B2's emptiness is caught by template suppression even though Fail if empty is off on B2. The message is suppressed when either block is empty.