Skip to content
Check out our new developer portal and join the Braze developer community!

Creating a catalog

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.

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.

Example catalog

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

id title price image_link
1234 Tales 7.49 USD
1235 Regeneration 22.49 USD

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.

{% 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:

{% 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.

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

This renders as the following:

Get Tales for just 7.49 USD!

Catalogs via API

You can leverage the Catalogs Endpoints to manage the growing data and information.

Managing catalogs

You can create a catalog using the Create Catalogs endpoint.

As you build more catalogs, you can also use the List Catalogs endpoint to return a list of the catalogs in an app group.

Managing catalog items

In addition to managing your catalogs, you can also use asynchronous and synchronous endpoints to manage the catalog items. This includes the ability to edit and delete catalog items, and to list catalog item details.

For example, if you want to edit an individual catalog item, you can use the /catalogs/catalog_name/items/item_id endpoint.

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

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

{% catalog_items Games 1234 %}

{{ items[0].image_link }}

Content Card composer with catalog Liquid tag used in the image field.

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

Example Content Card with catalog Liquid tags 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.

    "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:

{% 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 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.

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.

Managing catalogs

As you create more catalogs, you can leverage the Catalogs Endpoints to manage the growing data and information. This includes the ability to create, edit, and delete catalog items, and to list catalog item details.


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

Limitation Area Free version Catalogs Pro
Number of catalogs Up to 5 catalogs Up to 10 catalogs
Number of all catalogs items Up to 5,000 items Up to 100,000 items
Catalog storage Up to 100MB of catalog data Up to 2GB of catalog data
Filtered sets Up to 1 selection per catalog Up to 10 selections per catalog

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

Limitation Area Free version Catalogs Pro
CSV file size Up to 100MB for a single CSV file Up to 2GB for a single CSV file
Number of items Up to 5,000 items in a single catalog Up to 100,000 items in a single catalog
Number of fields Up to 30 fields (columns) Up to 30 fields (columns)
Characters limit for item value Up to 5,000 characters in one value. For example, if you had a field labeled description, the maximum number of characters within the field is 5,000. Up to 5,000 characters in one value. For example, if you had a field labeled description, the maximum number of characters within the field is 5,000.
Characters limit for item column name Up to 250 characters Up to 250 characters

Interested in upgrading your experience to Catalog Pro? Contact your account manager to get started.

New Stuff!