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.

Creating a catalog segment

1. Go to Segment Extensions > Create New Extension > Start With Template and select a template.
   

2. The SQL editor automatically populates with a template.
   
   This template joins user event data with catalog data to segment users who engaged with certain catalog items.

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

4. 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.
5. 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.

1
2
3
SELECT * FROM CATALOGS_ITEMS_SHARED
WHERE CATALOG_ID = 'XYZ'
LIMIT 10

Determining if you need to invert SQL

While it’s not possible to directly query for users with zero events, you can use Invert SQL to target these users.

For example, to target users who have fewer than three purchases, first write a query to select users who have three or more purchases. Then, select Invert SQL to target users with fewer than three purchases (including those with zero purchases).

Refreshing segment membership

To refresh the segment membership of any catalog segment, open the catalog segment and select Actions > Refresh > Yes, Refresh.

Designating refresh settings

If you don’t need your extension to refresh on a regular schedule, you can save it without using refresh settings, and Braze will default to generating your Segment Extension based on your user membership at that moment. Use the default behavior if you only want to generate the audience once and then target it with a one-off campaign.

Your segment will always begin processing after the initial save. Whenever your segment refreshes, Braze will re-run the segment and update segment membership to reflect the users in your segment at the time of refresh. This can help your recurring campaigns reach the most relevant users.

Setting up a recurring refresh

To set up a recurring schedule by designating refresh settings, select Enable refresh. The option to designate refresh settings is available for all types of Segment Extensions, including SQL segments, CDI segments, and simple form-based Segment Extensions.

Selecting your refresh settings

Within the Refresh Interval Settings panel, you can select the frequency at which this segment extension will refresh: hourly, daily, weekly, or monthly. You’ll also be required to select the specific time (which is in your company’s time zone) the refresh would occur, such as:

• If you have an email campaign that is sent every Monday at 11 am company time, and you want to ensure your segment is refreshed right before it’s sent, you should choose a refresh schedule of weekly at 10 am on Mondays.
• If you’d like your segment to refresh every day, select the daily refresh frequency and then choose the time of day to refresh.

Credit consumption and additional costs

Because refreshes re-run your segment’s query, each refresh for SQL segments will consume SQL segment credits, and each refresh for CDI segments will incur a cost within your third-party data warehouse.

Criteria to automatically disable stale extensions

Scheduled refreshes are automatically disabled once a Segment Extension is stale. A Segment Extension is stale if it meets the following criteria:

• Not used in any active campaigns or Canvases
• Not used in any segment that is in an active campaign or Canvas
• Not used in any segment that has analytics tracking turned on
• Hasn’t been modified in over seven days
• Hasn’t been added to a campaign or Canvas (including drafts), or segment in over seven days

If the scheduled refresh is disabled for a Segment Extension, that extension will have a notification that says so.

When you’re ready to use a stale Segment Extension, review the refresh settings, select the refresh schedule that matches your use case, and then save any modifications.

Use cases

Health app

Let’s say you have a 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 the dental value

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

SaaS platform

Let’s say you have B2B SaaS platform and want to segment users who are employees of an existing customer. You also have the following:

• A catalog Accounts that contains the different accounts that are currently using your SaaS platform, each assigned with an account ID
• A custom event Event Attendance with an “account ID” property that shares the same values as the “account ID” field in your catalog
• A Classification field within your catalog that contains the enterprise value

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

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.