Using catalogs in a message

After creating a catalog, you can reference non-user data in your Braze campaigns through Liquid. You can use catalogs in all of your messaging channels, including anywhere in the drag-and-drop editor where Liquid is supported.

Step 1: Add personalization type

In the message composer of your choice, select the plus icon to open the Add Personalization modal and select Catalogs Items for the Personalization Type. Then, select your Catalog Name. Using our previous example, we’ll select the “Games” catalog.

We can immediately see the following Liquid preview:

1
{% catalog_items Games %}

Step 2: Select catalog items

Next, it’s time to add your catalog items! Using the dropdown, select the catalog items and the information to display. This information corresponds to the columns in your uploaded CSV file used to generate your catalog.

For example, to reference the title and price of our Tales game, we could select the id for Tales (1234) as the catalog item and request title and price for the displayed information.

1
2
3
{% catalog_items Games 1234 %}
 
Get {{ items[0].title }} for just {{ items[0].price }}!

This renders as the following:

Get Tales for just 7.49!

Additional use cases

Multiple items

You aren’t limited to just one item in a single message. You can use the Add Personalization modal to add up to three catalog items at a time. To add more items to your message, select Add Personalization in the message composer and select the additional catalog items and information to display.

Check out this example where we add the id of three games, Tales, Teslagrad, and Acaratus, for Catalog Items and select title for Information to Display.

We can further personalize our message by adding some text around our Liquid:

1
2
Get the ultimate trio {% catalog_items games 1234 1235 1236 %}
{{ items[0].title }}, {{ items[1].title }}, and {{ items[2].title }} today!

This returns as the following:

Get the ultimate trio Tales, Teslagrad, and Acaratus today!

Using Liquid if statements

You can use catalog items to create conditional statements. For example, you can trigger a certain message to display when a specific item is selected in your campaign.

To do this, you’ll use a Liquid if statement in a format like this:

1
2
3
4
5
6
{% catalog_items Test-list %}
{% if {{items[0].first-item}} == true %}
Do this
{% else %}
Do that
{% endif %}

Note that you must declare the catalog list before using if statements. In the example above, Test-list is the catalog list.

Use case: Liquid if snippet

In this scenario, different messages will display if the custom attribute venue_name has more then 10 characters or less then 10 characters. If venue_name is blank, nothing will display.

1
2
3
4
5
6
7
8
{% catalog_selection_items item-list selections %} 
{% if items[0].venue_name.size > 10 %}
Message if the venue name's size is more than 10 characters. 
{% elsif items[0].venue_name.size < 10 %}
Message if the venue name's size is less than 10 characters. 
{% else %} 
{% abort_message(no venue_name) %} 
{% endif %}

Using images

You can also reference images in the catalog to use in your messaging. To do so, use the catalogs tag and item object in the Liquid field for images.

For example, to add the image_link from our Games catalog to our promotional message for Tales, select the id for the Catalog Items field and image_link for the Information to Display field. This adds the following Liquid tags to our image field:

1
2
3
{% catalog_items Games 1234 %}

{{ items[0].image_link }}

Here’s what this looks like when the Liquid is rendered:

Templating catalog items

You can also use templating to dynamically pull catalog items based on custom attributes. For example, let’s say a user has the custom attribute wishlist, which contains an array of game IDs from your catalog.

1
2
3
4
5
6
7
8
{
    "attributes": [
        {
            "external_id": "user_id",
            "wishlist": ["1234", "1235"]
        }
    ]
}

Using Liquid templating, you can dynamically pull out the wishlist IDs and then use them in your message. To do so, assign a variable to your custom attribute, then use the Add Personalization modal to pull a specific item from the array.

For example, to let a user know that Tales (an item in our catalog that they’ve wished for) is on sale, we can add the following to our message composer:

1
2
3
4
{% assign wishlist = {{custom_attribute.${wishlist}}}%}
{% catalog_items Games {{ wishlist[0] }} %}

Get {{ items[0].title }} now, for just {{ items[0].price }}!

Which will display as the following:

Get Tales now, for just 7.49!

With templating, you can render a different catalog item for each user based on their individual custom attributes, event properties, or any other templatable field.

Uploading a CSV

You can upload a CSV of new catalog items to add or catalog items to update. To delete a list of items, you can upload a CSV of item IDs to delete them.

Using Liquid

You can also manually piece together catalogs Liquid logic. However, note that if you type in an ID that doesn’t exist, Braze will still return an items array without objects. We recommend that you include error handling, such as checking the size of the array and using an if statement to account for an empty array case.

Templating catalog items including Liquid

Similar to Connected Content, you must use the :rerender flag in a Liquid tag to render a catalog item’s Liquid content. Note that the :rerender flag is only one level deep, meaning it won’t apply to any nested Liquid tag calls.

If a catalog item contains user profile fields (within a Liquid personalization tag), these values must be defined in Liquid earlier in the message and before the templating in order to render the Liquid properly. If the :rerender flag isn’t provided, it will render the raw Liquid content.

For example, if a catalog named “Messages” has an item with this Liquid:

To render the following Liquid content:

1
2
3
4
Hi ${first_name}

{% catalog_items Messages greet_msg :rerender %}
{{ items[0].Welcome_Message }}

This will display as the following:

1
2
3
Hi Peter,

Welcome to our store, Peter!