Configure a catalog trigger

Catalog triggers start a scenario when the selected 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

Catalogs managed through Data hub: Catalog triggers need a catalog linked to a Data hub item type: a product catalog from a product item type, or a general catalog from a custom item type. Catalog triggers don't support general catalogs that you create directly in Marketing.

Catalog trigger structure

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

Select items

1. Choose the catalog to monitor. If several item types publish to the same Marketing project, choose the catalog by the name you set for that item type's destination.
2. Optionally, choose the attribute and add item filters that decide which items qualify, independent of customer behavior.

For example:

For a product item type with separate product and variant catalogs, choose which catalog to monitor. Custom item types have one general 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.

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.

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.

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.

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.

Example

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

Custom data example

The field and event names in this example are illustrative; use the names from your setup.

An article announcing an event has item ID NEWS-42 and an event_date attribute. Configure an Item date trigger for one day before that date. Match customers who viewed the article in the past 30 days, using the article_id property on an article_view event. That property must contain the catalog item ID, NEWS-42, even if the source record has a different ID.

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.

It stays available for personalization for 7 days after the trigger activates, then it's no longer accessible for that batch.

The catalog_triggers object

Each item in catalog_triggers has the following fields:

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 }}