Creating a catalog

Creating a catalog involves importing a CSV file of non-user data into Braze. This allows you to 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.

Some common use cases for catalogs include:

• Products
• Services
• Food
• Upcoming events
• Music
• Packages

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.

Preparing your CSV file

Before creating a catalog, be sure to have your CSV file ready if your preferred catalog creation method is to upload.

CSV file guidelines

Note these guidelines when creating 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 1,000 fields (columns)
• Maximum field (column) name of 250 characters
• Maximum 100 MB for all CSV files combined across your company (Free)
• Maximum CSV file size of 2 GB (Pro)
• Maximum field value (cell) of 5,000 characters
• Only letters, numbers, hyphens, and underscores for id and header values

We also recommend formatting all text in your CSV files as lowercase. Make sure you’re encoding your CSV file using the UTF-8 format to upload your CSV file in the next step successfully.

Selecting your method

To create a catalog, go to Data Settings > Catalogs.

Select Create New Catalog, then choose to either Upload CSV or Create in browser.

Method 1: Upload CSV

1. Drag and drop your file to the upload zone, or click Upload CSV and choose your file.
   
   
   
2. Select one of the following data types for each column: boolean, number, string, or time.
   
   
   
3. Give your catalog a name. Keep in mind the following requirements for a catalog name:
   • Must be unique
   • Maximum of 250 characters
   • Can only include numbers, letters, hyphens, and underscores
     
     
4. (optional) Add a description for the catalog.
5. Click Process Catalog to create the catalog.

You can also use templates in a catalog name. For example, you can use the following:

1
2
3
4
{% assign language = "content_spanish" %}

{% catalog_items {{language}} fall_campaign %}
{{ items[0].body }}

You can also update the CSV file after selecting to create a catalog in the browser. Click Update Catalog > Upload CSV, then select whether to update, add, or delete items in your catalog.

Method 2: Create in the browser

1. Enter a name for your catalog. Keep in mind the following requirements for your catalog name:
   • Must be unique
   • Up to 250 characters
   • Can only include numbers, letters, hyphens, and underscores
     
     
     
2. (optional) Type a description for your catalog.
3. Select the catalog you’ve just created from the list Catalogs page to update your catalog.
4. Select Update Catalog > Add fields to add your fields. Then, enter the Field name and use the dropdown to select the data type. Repeat as needed.
   
   
   
5. Select Update Catalog > Add items to add an item to your catalog by entering the information based on the fields you previously added. Then, select Save Item or Save and Add Another to continue adding your items.
   

You can also upload a CSV file after selecting to create a catalog in the browser.

Tutorial: Creating a catalog from a CSV file

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

We’ll create the catalog by uploading a CSV file. The data types for id, title, price, and image_link are string, string, number, and string, respectively.

Next, we’ll name this catalog “games_catalog” and click the Process Catalog button. Then, Braze will check the catalog for any errors before catalog creation.

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

After creating the catalog, you can begin referencing the catalog in a campaign.

Managing catalogs through API

As you build more catalogs, you can also use the List catalogs endpoint to return a list of the catalogs in a workspace.

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.

Catalog tiers

The following table describes the differences between the free and pro version of catalogs:

Catalog storage

Free version

The storage size for the free version of catalogs is up to 100 MB. You can have unlimited items as long as it’s under 100 MB. Selections will contribute to your storage. The more complex a selection is, the more storage it will take up. There will also be a size mismatch between the CSV catalog data and the representation of that data in our datastore.

Catalogs Pro

At a company level, the maximum storage for Catalogs Pro is based on the size of catalog data. The storage size options are: 5 GB, 10 GB, or 15 GB. Note that the free version’s storage (100 MB) is included in each of these plans.