Skip to content

Catalog segments

Catalog segments are a type of SQL Segment Extension that is created by combining catalog data with data from custom events or purchases. They can be referenced in a segment and then targeted by campaigns and Canvases.

Catalog segments use SQL to join data from catalogs and data from custom events or purchases. To do so, you must have a common identifier field across your catalogs and your custom events or purchases. For example, the value of an item ID in a catalog must match the value of a property in a custom event.

Use cases


  • Catalog of products where the item ID value is equal to the Shopify ID
  • Custom event Made Order with a property (such as shopify_id) that has the same value as the Shopify ID

Health app

  • Catalog of different doctors a patient can book, each with an item ID
  • Custom event Booked Visit with a property that has the same value as the item ID

Creating a catalog segment

  1. Go to Segment Extensions > Create New Extension > Start With Template and select the template Catalog segment.
    Modal with "Catalog segment" selected as the template to create.
  1. The SQL editor automatically populates with a template.
    SQL editor with a pregenerated template.
    This template joins user event data with catalog data to segment users who engaged with certain catalog items.

  2. Use the Variables tab to provide the necessary fields for your template before generating your segment.
    For Braze to identify users based on their engagement with catalog items, you need to do the following:
    - Select a catalog that contains a catalog field
    - Select a custom event that contains an event property
    - Match your catalog field and event property values

Here are guidelines to select the variables:

Variable field Description
Catalog The name of the catalog you’re using to target users.
Catalog field The field in your catalog that contains the same values as your Custom event property. This is often a type of ID. In the ecommerce use case, this would be shopify_id.
Custom event The name of your custom event, which is the same event that contains a property with values matching your Catalog field. In the ecommerce use case, this would be Made Order.
Custom event property The name of your custom event property, which matches values with your Catalog field. In the ecommerce example use case, this would be Shopify_ID.
  1. If needed, fill in additional optional fields for your use case to segment by a particular field value within your catalog:
    • Catalog field: A particular field (column name) within this catalog
    • Value: A specific value within that field or column

      Using the health app as an example, let’s say that within the catalog for each doctor you could book, there’s a field called specialty that contains a value such as vision or dental. To segment users who have visited any doctors with the value dental, you can select specialty as the Catalog field, and select dental as the Value.
  2. After creating a SQL Segment, we recommend clicking Run Preview to see if your query returns users or if there are errors. For more information about previewing query results, managing SQL Segment Extensions, and more, check out SQL Segment Extensions.

Use case

Let’s say you have health app and want to segment users who have booked a visit for the dentist. You also have the following:

  • A catalog Doctors that contains the different doctors a patient can book, each assigned with a doctor ID
  • A custom event Booked Visit with a doctor ID property that shares the same values as the doctor ID field in your catalog
  • A speciality field within your catalog that contains dental value

You would set up a catalog segment by using the following variables:

Variable Property
Catalog Doctors
Catalog field doctor ID
Custom event Booked Visit
Custom event property doctor ID
(Under Filter SQL Results) Catalog field Specialty
(Under Filter SQL Results) Value Dental

Frequently asked questions

Does running a catalog segment consume SQL Segment Extension credits?

Yes, catalog segments are powered by SQL and consume SQL Segment Extension credits. To learn more, check out SQL Segments usage.

Does creating a catalog segment consume SQL Segment Extension allotments?

Yes. In the same way SQL Segment Extensions count toward your Segment Extension allotment, catalog segments also count toward that allotment.

I have a catalog segment use case that the current template doesn’t serve. How should I set that up?

Reach out to your customer support manager or Braze Support for additional guidance.

New Stuff!