Creating User Lists with Catalog Data

Catalog in Segmentation lets you combine catalog data with user profile information and event history to build targeted audiences for personalized campaigns. This feature relies on the Matches Catalog Data comparator, which segments users by matching values stored in your catalogs. You can then query your catalog to find the items you want to use for matching users.

You can save catalog-based segmentation queries as scheduled lists that refresh automatically on a daily cadence, or as static lists when you need results right away.

# In this article

# Required permissions

To save the results of a segmentation query as a list, you'll need the Create and Manage Lists permission.

# Using the Matches Catalog Data comparator

The Matches Catalog Data comparator lets you find users based on data stored in your catalogs. Instead of segmenting only with profile fields or event history, you can match users to specific products, services, or other catalog items.

When you use Matches Catalog Data, Iterable follows this process:

1. Select a user field: Choose a user profile field or event field that contains data you want to match against your catalog.
2. Select a catalog field: Choose the corresponding field in your catalog that should match the user or event field.
3. Define your catalog query: Set up criteria to find specific items in your catalog (like "all running shoes" or "restaurants in Paris").
4. Iterable finds the matches: The system finds all users whose selected field value matches any of the catalog items returned by your query.
5. Save as a list: Save the results as a scheduled or static list. If you save as a scheduled list, it automatically refreshes on a defined schedule.

Example:

Let's say you want to find users who have viewed any running shoe product:

• User field: lastProductViewed (contains product IDs like "nike-air-max-3000")
• Catalog field: productId (contains the same product IDs)
• Catalog query: Find all items where category = "Running Shoes"
• Result: Users who have viewed any running shoe product

This approach lets you build highly targeted audiences by first defining what products you're interested in, then finding all users who have interacted with those specific products.

# Field matching requirements

When you select a user profile or event field to segment by, you must select a matching field in your catalog.

A matching field can be:

• A field name in the catalog.

• A key value (the unique identifier for a catalog item).

  If you choose to match by a key value, you can only match it to a user profile or event field with the string data type.

The matching field does not need to have the same name as the user profile or event field, but keep these requirements in mind:

• All catalog items must have the matching field set. If one or more of the catalog items returned from your query does not have a value for the matching field, the segmentation query fails.

  TIP

  To avoid query failure, add a clause to your query that ensures the field is set. For example, use Where > myField > Is Set.

• Data types must match exactly. The data type of the matching catalog field must match the user profile or event field exactly. For example, string must match string and boolean must match boolean.

• You can’t match by a top-level object. However, you can match on an object’s subfields, which are listed in dot notation in the dropdown menu. For example, you can’t match on order, but you can match on order.total.

• Matching values must match exactly. This query is case-sensitive.

# Catalog query requirements and limitations

When you run a Matches Catalog Data query, Iterable queries the catalog for the catalog items that match your criteria.

Here are some requirements and limitations to keep in mind:

• Catalog item query limits: Catalog searches are limited to 10,000 matching catalog items, returned in random order.

  WARNING

  If your catalog query has more than 10,000 results, the returned catalog items can vary each time you run the query. That means the list of returned users can vary, too.

• Handlebars aren’t supported: You can’t use Handlebars expressions to locate field values in a catalog segmentation query.

• Catalog query values are case-sensitive.

  TIP

  Use Preview Results to confirm that the value you entered matches the value stored in your catalog.

# Creating a Catalog segmentation query

Here’s how to segment users based on catalog data.

# Step 1: Start a new segmentation query

1. Go to Audience > Segmentation.

2. Select whether you want to find users who match any, all, or none of your search criteria.

3. Click the Choose a property... dropdown and select the user profile field or event type you want to segment by.

4. For where, select the specific user profile or event field you want to segment by.

5. For the comparator, select Matches Catalog Data.

   

# Step 2: Match the user profile field to a catalog field

Next, search for the product or service data you store in Catalog and connect it to the user data you selected in Step 1.

1. Click Add Criteria to open the Match from Catalog menu.

2. Select the catalog you want to search.

3. Select the catalog field to use for matching. Make sure to select a field whose values match the values stored in the user profile or event field you selected earlier.

   

# Step 3: Define the catalog query

Once you’ve matched the user profile or event field to a catalog field, define the catalog query used to find the relevant catalog items.

1. Select whether you want to find catalog items that match any, all, or none of your search criteria.

2. Select the field and comparator to segment by.

3. In value, enter the value you want to segment on. This field accepts free text, but it doesn’t support Handlebars.

4. Continue building your catalog query by adding more conditions to narrow the results to the catalog items you want to target.

# Step 4: Preview your catalog query

1. Click Preview Results to confirm that your catalog query returns the expected items. The preview shows a maximum of 20 results.

2. If you need to make changes, click Edit and update the query.

3. When you’re confident in the catalog query, click Apply Query.

   

# Step 5: Save as a scheduled or static list

When you’re ready to save your query, click Save As and select Scheduled List or Static List.

Once you’ve saved your list, you can use it anywhere else you use lists, like for campaigns or as an entry source for a journey.

# Working with Scheduled Lists

Scheduled lists are designed for queries that match users with catalog data. While dynamic lists refresh at send time, scheduled lists recalculate membership once every 24 hours at a time you choose. During each refresh, Iterable updates the list to reflect the current batch of users who meet your catalog segmentation criteria.

Scheduled lists can be used anywhere you use lists in Iterable. They’re useful for recurring campaigns that depend on changing catalog data, such as weekly promotions, back-in-stock alerts, and subscription reminders.

# Scheduled list limitations

Scheduled lists have these constraints:

• They can only be created from queries that use the Matches Catalog Data comparator.
• A newly created scheduled list is empty until it reaches its first scheduled refresh.
• You can have a maximum of 10 scheduled lists per project.
• Each scheduled list can contain up to 1 million users. If your query returns more than that, some matching users are skipped. The 1 million users included in the list are added in a nondeterministic order, so the users in the list can differ between refreshes.
• Each scheduled list can contain only one catalog query.
• You can’t convert an existing list to a scheduled list, or convert a scheduled list to another list type. To change the list type, save the query again as a new list.

# Saving query results as a scheduled list

After you create the segmentation query you want, click Save As > Scheduled List.

Give the list a name, optionally add a description, and choose the daily refresh time. The time zone for that refresh time comes from your project’s default time zone.

# Using scheduled lists in campaigns

When you select a scheduled list as the audience for a campaign, the recipients are the users saved to the list during the most recent refresh before send time. If you want the freshest batch of users, schedule the campaign to send shortly after the list’s refresh time.

# Editing scheduled lists

You can edit both a scheduled list’s refresh time and the segmentation query that defines who belongs in the list.

# Changing the refresh time

Open the scheduled list and click Edit Refresh. Adjust the schedule, then click Save.

Scheduled lists require a full 24-hour interval between refreshes. This refresh cycle can’t be forced or manually triggered early. If you move the refresh to an earlier time, Iterable skips the first new window and waits until the next day so that at least 24 hours have passed since the last refresh.

# Changing the query

At any time, you can edit the segmentation query that defines the list’s criteria. Before you do, consider checking the Referenced In tab on the list’s details page to see which campaigns use that list. This is especially important for campaigns in the Ready, Scheduled, Running, or Recurring state, which haven’t been sent yet.

To save changes to the query, you have two options:

• Update the original scheduled list: Add, change, or remove criteria in the query builder, then click Update and confirm with Update List.

• Save the updated query as a new scheduled list: Update the query, click View Results to fetch the updated users, then click Save As > Scheduled List to create a new scheduled list based on the new criteria.

# Use cases

Here are a couple of ways you can use Catalog in segmentation.

# Promote a new restaurant to nearby users

Let’s say you’re a marketer for a food delivery company. A new Thai restaurant has just opened in Paris, and you want to promote it to users who have ordered from Thai restaurants in Paris within the last 30 days. Here’s one way to do that:

1. Create a new segmentation query and select the event subfield you use to track orders, such as orderedDelivery.cuisine.

2. Select Matches Catalog Data as the comparator.

3. Click Add Criteria.

4. In Match from Catalog, select the catalog that contains all restaurants, such as Restaurants.

5. Select the catalog item field that identifies a restaurant’s category, such as cuisine.

6. Set up your catalog query to find Thai restaurants in Paris.

7. Apply the catalog query.

8. Back on the Segmentation page, add another condition to narrow the results to the past 30 days.

9. Click Refresh Results to return a list of all users who have ordered from a Thai restaurant in Paris in the last 30 days.

# Notify users when their free trial is about to end

Let’s say you’re a marketer for a company that sells enterprise software. You store account membership data on user profiles and free trial expiration dates in Catalog. You need to create a list of users whose free trial expires one week from today. Here’s how you might do that:

1. Create a new segmentation query and select the field you use to track account membership on user profiles, such as accountId.

2. Select Matches Catalog Data as the comparator.

3. Click Add Criteria.

4. In Match from Catalog, select the catalog that contains your free trial memberships, such as Free-Trials.

5. Select the catalog field that identifies each account. In this example, it’s the Key Value.

6. Set up your catalog query to find trials expiring in the next 7 days.

   NOTE

   To learn about working with relative dates, see Using Relative Dates in Segments and Journeys.

7. Apply the catalog query.

8. Click Refresh Results to return a list of all users associated with accounts whose free trials expire in 7 days or less.

# Tips and troubleshooting

# Query failure

If one or more of the catalog items returned from your query doesn’t have the specified matching field, the segmentation query fails.

To avoid this, add a clause to your query to ensure the field is set. For example, use Where > myField > Is Set.

# Missing catalog fields

If you don’t see an expected catalog field in the query builder, its field type may not be defined yet. Defining a field type is required before a field can appear in the query builder. To learn more, see Defining Data Types for Catalog Item Fields.

# Want to learn more?

For more information about some of the topics in this article, check out these resources. Iterable Academy is open to everyone—you don't need to be an Iterable customer!

Iterable Academy

• Foundations: Lists and Segmentation
• Catalog 101
• User Engagement Identification Through Segmentation

Support docs

• Segmentation Overview
• Lists Overview
• Catalog Overview
• Using Relative Dates in Segments and Journeys
• Defining Data Types for Catalog Item Fields