Catalogs

You can use catalogs to reference non-user data in your Braze campaigns through Liquid.

To do so, first import your catalog (a CSV file of non-user data) into Braze, and then access that information to enrich your messages. You can bring in any type of data into a catalog. This data is typically some sort of metadata from your company such as product information for an eCommerce business, or course information for an education provider.

Once this information is imported, you can begin accessing it in messages in a similar way to accessing custom attributes or custom event properties through Liquid.

If you’d like to share your feedback on this feature or make a request, contact the Braze Catalogs team at catalogs-product@braze.com.

Creating a catalog

To create a catalog in Braze, upload a CSV file to the Catalogs page. Each CSV file you upload will be its own distinct catalog. You can also download and reference this sample CSV file to follow along the steps for creating a catalog.

Step 1: Create your CSV

First, create your CSV file. The first column of the CSV file must be a header of id, and each item’s id must be unique. All other column names must be unique. Additionally, the following limitations apply to catalog CSV files:

• Maximum of 5,000 items (rows)
• Maximum of 30 fields (columns)
• Maximum field (column) name of 250 characters
• Maximum CSV file size of 100MB
• Maximum field value (cell) of 5,000 characters
• Maximum field value (cell) size of 0.5KB
• Only letters, numbers, hyphens, and underscores for id and header values

Ensure that you are encoding your CSV file using the UTF-8 format in order to successfully upload your CSV file in the next step. We also recommend that you format all text in your CSV files as lowercase.

For this tutorial, we’re using a catalog that lists two games, their cost, and an image link.

Step 2: Upload your CSV

After you’ve created your CSV, navigate to the Catalogs page and upload the file. Drag and drop your file to the upload zone, or click Upload CSV and choose your file.

Give your catalog a name. Keep in mind the following limitations for your catalog name:

• Must be unique
• Maximum of 250 characters
• Can only include numbers, letters, hyphens, and underscores

Note that you cannot use templates in a catalog name. For example, you cannot have the following as the catalog name or else the call will fail.

1
{% catalog_items custom_attribute.${catalog} item1, item2 %}

Step 3: Select your data type

Select one of the following data types for each column:

• Boolean
• Number
• String
• Time

Step 4: Enter a catalog name

Enter a unique name for your catalog. This name can only contain numbers, letters, hyphens, and underscores. Optionally, you can also add a description for your catalog.

Lastly, click the Create Catalog button to finish creating your catalog!

Note that you won’t be able to edit this name once the catalog is created. You can delete a catalog and reupload an updated version using the same catalog name.

Using catalogs in a message

You can use catalogs in all of your messaging channels, including anywhere in the Drag & Drop Editor where Liquid is supported.

Step 1: Add personalization type

In the message composer of your choice, click 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 the tales_storefront item, we could select the tales_storefront as the catalog item and title and price for the displayed information.

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

This renders as the following:

Get Tales for just 7.49 USD!

Additional use cases

Multiple items

You aren’t limited to just one item in a single message! Simply insert the additional catalog items and information to display using the Add Personalization modal. Note that you can add up to three catalog items only.

Check out this example where we add tales_storefront, teslagrad_storefront, and acaratus_storefront 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 tales_storefront teslagrad_storefront acaratus_storefront %}
{{ 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 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 tales_storefront 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 tales_storefront %}

{{ 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": ["tales_storefront", "teslagrad_storefront"]
        }
    ]
}

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_storefront (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 tales_storefront {{ 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 USD!

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.

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.

Limitations

Refer to the following table for limitations that apply at a company level:

The following table describes the limitations that apply at a catalog level:

Interested in upgrading your experience to Catalog Pro? Contact the Braze Catalogs team at catalogs-product@braze.com for more information.