Creating User Lists with Catalog Data

Iterable’s Catalog feature lets you store valuable data about your products and services right in Iterable. The Matches Catalog Data comparator lets you use this data in the Segmentation tool — so you can build audiences using all of the data you store in Iterable.

For example, let’s say you're a marketer at a food delivery company and you want to send a campaign about the grand opening of a new Thai restaurant to users who have ordered Thai food in the last 30 days. You store information about the restaurants your users can order from (like the type of cuisine they serve) in Catalog, and you store information about users' food preferences and order history on their user profiles.

With the Matches Catalog Data segmentation comparator, you can connect data from user profiles with the data you store in Catalog — so you can build highly targeted lists of users and send more personalized campaigns.

# 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.

# Working with Catalog data in a segmentation query

Here’s how to build a list of users based on data stored in Catalog.

# Step 1: Set up a segmentation query

The first step is to search for the user data you’re interested in. To do this, set up a segmentation query that you’ll connect to your Catalog data in a later step.

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 property or event type you want to segment by. (This example uses the default option, Contact Property.)

   

4. For where, select the user or event data field you want to segment by (for example, lastOrderLocation). You’ll match this field to a catalog value in a later step.

   

   NOTE

   You can’t segment by a top-level object (an event or property labeled object in the dropdown menu). However, you can segment by an object’s subfields, which are labeled date, string, long, etc. These items are listed in dot notation in the dropdown menu (for example, orderEvent.price).

5. For the comparator, select Matches Catalog Data.

   

6. Click Add Criteria. This brings up the Match from Catalog menu, where you’ll set up the conditions of your Catalog query (see Step 2).

   

# Step 2: Set up the Catalog query

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

1. Select the catalog you want to search. (You can select one catalog per segmentation query).

   

2. Then, select the catalog field that matches the user data field you selected in the previous step. This brings up the Catalog query builder.

   You can segment by a specific field name or by a key value (the unique identifier for one of your catalog items). The user or event data field you selected in Step 1 must match a specific field in the catalog — either the key value or another property in the catalog.

   NOTE

   The query builder accepts all data types (strings, dates, integers, longs, doubles, and booleans), but the data types you select on each side of your query must match. For example, you can’t compare a string to a boolean. You can compare a string to another string, a number to another number, etc.

   (If you choose to segment by a key value, you can only match it to a string.)

   

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

4. Select the field you want to segment by.

5. Select a comparator.

6. For value, type the property to segment by. (This field accepts a text entry and doesn’t support Handlebars.)

   NOTE

   This field is case-sensitive. If you enter london but the value is capitalized (London) in your catalog metadata, your search won’t return the right results. Use the Preview results button to ensure your entry matches the value stored in your catalog (see Step 3).

# Step 3: Preview and save your Catalog query

While you’re setting up your Catalog query, check that it returns the information you expect. This can help you identify and fix any issues before you run the full query in the next step.

1. To preview your query results, click Preview results. This returns a list of items that match your current Catalog query. (The preview shows a maximum of 20 results at a time.)

2. If you need to make any changes, click Edit. You can also use the undo/redo arrows to quickly fix any mistakes you make.

3. When you’re confident your query returns the results you’re looking for, click Apply query.

# Step 4: Generate and save the list

When you’re finished setting up the two sides of your query, it’s time to find all the users who match your criteria.

1. Click Refresh results, and a list of users who match your criteria will appear at the bottom of the page.

   NOTE

   Results are capped at 10,000 matching catalog items, and these items are returned in random order. If more than 10,000 catalog items match your specified criteria, the 10,000 items that are returned may not be the same set of items each time you run the query.

2. Click Save list… and select Save as a new static list. (To learn more about static and dynamic lists, see Lists Overview.)

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

# Use cases

There are so many ways you can use this new functionality, but here are a couple of ideas!

# 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. The way you set this up depends on the way your data is structured. Let's assume that you have:

• A custom event called orderedDelivery that's triggered each time a user orders a food delivery. This event includes information about the type of cuisine the user ordered in a subfield called cuisine.

• A catalog called Restaurants that contains all of your restaurants, including their location (metro) and the type of cuisine they serve.

Here's one way you could create the list of users you're looking for:

1. Create a new segmentation query, and select a subfield of the event that you use to track orders (for example, orderedDelivery.cuisine).

   

2. For the comparator, select Matches Catalog Data.

3. Click Add Criteria.

4. In the Match from Catalog menu, select the catalog that contains all the restaurants customers can order from (for example, Restaurants).

   

5. Select the catalog field that you want to filter on. For example, if a restaurant catalog item has fields like cuisine and averagePrice, you might choose cuisine because it will allow you to specify Thai.

   

6. Set up your Catalog query. It might look like this:

   

7. Apply the Catalog query.

8. On the Segmentation page, add another condition to your query that narrows the results to the past 30 days. It might look like this:

   

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 expire

Let’s say you’re a marketer for a company that sells three enterprise software products: Fiterable, Fiterable Nutrition, and Fiterable Family. Employees of the organizations you market to can try your products for free for 30 days, so multiple users can be associated with the same account. You store account membership data on user profiles, and you store free trial expiration dates in Catalog. You need to create a list of users whose free trial of your Fiterable product 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 users' account membership (for example, accountId). In this example, this field is a Contact Property found on users' profiles.

   

2. Select the Matches Catalog Data comparator.

3. Click Add Criteria.

4. In the Match from Catalog menu, select the catalog that contains all of your free trial memberships (for example, Free-Trials).

5. Select the catalog field that's associated with each enterprise account (in this example, it’s the Key Value).

   

6. Set up your Catalog query. It might look like this:

   

   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 who are associated with accounts that have free trials of your Fiterable product expiring in 7 days or fewer.

# Current feature limitations

Since this feature is still under active development, it’s important to note that some functionality is limited. Here are the current limitations of this beta feature (which may or may not be updated in a later release):

• If one or more of the catalog items that’s returned from your Catalog query doesn’t have the matching field, the Segmentation query fails.

  NOTE

  To avoid this, you can add a clause to the query you set up on the Match from Catalog page. For example, if you’re segmenting by a field called isActive, you could add Where > isActive > Is Set.

• It isn’t possible to use this new feature in journey filter tiles.

• Lists can only contain one Matches Catalog Data comparator and can’t reference other lists that segment based on Catalog data.

• You can only save the results of a Matches Catalog Data query as a static list.