Guides
HomeEngagementOther resources
  1. Working with Scenarios
  2. Triggers
  3. Catalog triggers

Configure a catalog trigger

Catalog triggers start a scenario when your product catalog changes, and reach only the customers who showed interest in the affected item. Every trigger shares three parts, plus fields specific to each trigger type. For background on the feature, see Catalog triggers.

Prerequisites

  • Item collections in Data hub: Catalog triggers need Data hub item collections (unified product data). They don't support legacy product-specific catalogs.

Catalog trigger structure

Every catalog trigger is configured using the following settings and filters.

Select an item

Select items

  1. Choose the catalog to monitor.
  2. Optionally, choose the attribute and add item filters that decide which items qualify, independent of customer behavior.

For example:

If your setup uses separate catalogs for variants, choose whether to monitor the product or the variant catalog. You can use up to 10 attributes per item filter.

Trigger when

Triggers are configured based on the trigger type. Some types let you configure a threshold or percentage; others are fixed — a new arrival, for example, activates whenever a new item is added. For more information, see Trigger types and their fields.

Available operators depend on the selected column’s data type and the trigger type.

Configure the trigger.

Safety wait

All catalog triggers require a safety wait. It waits the time you set after the change, then rechecks the item and continues only if the condition still holds — for example, the price is still reduced, or the stock is still at or above the threshold.

You can set the duration between 1 minute and 24 hours. To make full use of the system's batching capabilities, set the safety wait to at least 15 minutes.

🚧

Warning

A safety wait shorter than 15 minutes combined with a large item collection update may result in the scenario running more times than expected.

Audience matching filters

Audience matching filters define who counts as interested in an item, and so qualifies for the trigger. The scenario runs for a customer only if they have shown interest in that specific item, based on the events and lookback windows you configure. You can also explicitly exclude customers based on event conditions.

Configure audience matching filter.
📘

Note

The audience matching filter uses the same interest system as API triggers. The interest setups you build here count toward that shared limit.

Set the qualifying event, a minimum number of occurrences, and a lookback window—for example, viewed this item at least 1 time in the last 30 days. To exclude, add a second condition—for instance, exclude anyone who purchased that item in the same period.

📘

Note

Once the scenario starts, you can adjust only the frequency—the minimum number of occurrences and the lookback window. The other audience matching conditions are locked.

Item limits

Two limits apply each time the scenario runs for a customer.

  • Minimum: the number of items in the batch a customer must have shown interest in. If fewer items match, the scenario is skipped for that customer.
    • The default is 1 and can be adjusted using Require at least [x] matching items per customer at the bottom of the Audience matching filters section
  • Maximum: the number of matched items available for personalization, prioritized by customer interest.
    • The maximum is fixed at 10.

The limit applies per batch, not to a customer's total interest across all batches. If a customer's matched items span multiple batches, each batch is checked on its own. Items from other batches don't count toward it.

📘

Note

With a minimum of 1, a customer can qualify from every batch that contains at least one matching item. Use a frequency policy to control how often the same customer receives communications across multiple batches.

Example
If the minimum you set is 4 and a customer is interested in 6 items on sale:

Batch splitOutcome
All 6 items land in one batchThe batch meets the minimum, and the scenario runs.
The 6 items split evenly across two batches (3 each)Neither batch meets the minimum, so the scenario is skipped for both.
The items split as 2 and 4 across two batchesOnly the second batch meets the minimum. The scenario runs for that batch alone.

Reference catalog trigger data in messages

Each time a catalog trigger is evoked, the scenario has access to a catalog_triggers object—a list of dictionaries, one for each item that qualifies for the trigger. Use these objects in Jinja to pull item data into your message templates.

📘

Note

This data is also available in the Personalization Wizard to select fields via the UI.

The catalog_triggers object

Each item in catalog_triggers has the following fields:

FieldDescription
currentAll catalog properties for the item at the time the trigger fired — for example, brand, price, stock_level, title, url.
oldThe watched attribute before the change. Which field appears here depends on the trigger condition you configured — for example, a price reduction trigger includes the previous price.
item_idThe item's ID in the catalog.
catalog_idThe ID of the item collection the trigger is watching.

Items are ordered by overall customer interest, with the highest-interest item first.

Access trigger data

{# Current value of the first (highest-interest) item #}
{{ catalog_triggers[0].current.price }}

{# Old value of the first item — for example, the price before a drop #}
{{ catalog_triggers[0].old.price }}

{# Item ID of the first item #}
{{ catalog_triggers[0].item_id }}

{# Last item in the batch #}
{{ catalog_triggers[-1].current.brand }}

{# Loop over all items #}
{% for item in catalog_triggers %}
  {{ item.current.title }} — {{ item.current.price }}
{% endfor %}

{# Number of items in this trigger batch #}
{{ catalog_triggers | length }}

© Bloomreach, Inc. All rights reserved.