Custom Events

Custom events are actions taken by, or updates about, your users. They’re best suited for tracking high-value user interactions within your application. Logging a custom event can trigger any number and type of follow-up campaigns, and enables the listed segmentation filters on the recency and frequency of that event.

For more on using custom events in your messaging strategies, check out our LAB course on Custom Events & Attributes!

Logging Custom Events

Listed below are the methods across various platforms that are used to log custom events. Within these pages, you will also be able to find documentation on how to add properties and quantities to your custom events.

Custom Event Segmentation Filters

Segmentation Options Dropdown Filter Input Options
Check if the custom event has occurred more than X number of times MORE THAN NUMBER
Check if the custom event has occurred less than X number of times LESS THAN NUMBER
Check if the custom event has occurred exactly X number of times EXACTLY NUMBER
Check if the custom event last occurred after X date AFTER TIME
Check if the custom event last occurred before X date BEFORE TIME
Check if the custom event last occurred more than X days ago MORE THAN NUMBER OF DAYS AGO (Positive Number)
Check if the custom event last occurred less than X days ago LESS THAN NUMBER OF DAYS AGO (Positive Number)
Check if the custom event occurred more than X (Max = 50) number of times MORE THAN in the past Y Days (Y = 1,3,7,14,21,30)
Check if the custom event occurred less than X (Max = 50) number of times LESS THAN in the past Y Days (Y = 1,3,7,14,21,30)
Check if the custom event occurred exactly X (Max = 50) number of times EXACTLY in the past Y Days (Y = 1,3,7,14,21,30)

Custom Event Analytics

Braze notes the number of times these events have occurred as well as the last time they were performed by each user for segmentation. On the Custom Events page in the Dashboard, you can view in aggregate how often each custom event occurs, as well as by segment over time for more detailed analysis. This is particularly useful to view how your campaigns have affected custom event activity by looking at the gray lines Braze overlays on the time series to indicate the last time a campaign was sent.


Custom Events Analytics Not Showing?

Please note that Segments created with custom event data cannot show previous historic data from before they were created.

Custom Event Storage

All User Profile data, including custom event metadata (first/last occurrence, total count, and X in Y over 30 days) is stored as long as each profile is active.

Custom Event Properties

With custom event properties, you can set properties on custom events and purchases. These properties can then be used for further qualifying trigger conditions, increasing personalization in messaging, and generating more sophisticated analytics through raw data export.

The properties values should be an object where the keys are the property names and the values are the property values. Property names must be non-empty strings less than or equal to 255 characters, with no leading dollar signs ($).

Property values can be any of the following data types:

Data Type Description
Numbers As either integers or floats
Datetimes Formatted as strings in ISO-8601 or yyyy-MM-dd'T'HH:mm:ss:SSSZ format. Not supported within arrays.
Strings 255 characters or fewer.
Arrays Arrays cannot include datetimes.
Objects Objects will be ingested as strings.

Event property objects that contain array or object values can have an event property payload of up to 50KB.

For example, if an eCommerce application wanted to send a message to a user when they abandon their cart, it could additionally improve its target audience and allow for increased campaign personalization by adding a custom event property of the ‘cart value’ of users’ carts.


Custom event properties can also be used for personalization within the messaging template. Any campaign using Action-Based Delivery with a trigger event can use custom event properties from that event for messaging personalization. If a gaming application wanted to send a message to users who had completed a level, it could further personalize the message with a property for the time it took users to complete that level. In this example, the message is personalized for three different segments using conditional logic. The custom event property called time_spent, can be included in the message by calling {{event_properties.${time_spent}}}.

You can change the data type of your custom event property, but please be aware of the impacts of changing data types after data has been collected.

In regards to subscription usage, custom event properties enabled for segmentation with the filters X Custom Event Property in Y Days or X Purchase Property in Y Days are all counted as separate data points in addition to the data point counted by the custom event itself.

Custom Event Property Storage

Custom event properties are designed to help you increase targeting precision and make messages feel even more personalized. Custom event properties can be stored within Braze in both the short and long term.

If you would like to segment on the values of event properties, you have two options:

  1. Within 30 days: Braze support personnel can enable event property segmentation based on the frequency and recency of specific event property values within Braze Segments. If you’d like to leverage event properties within Segments, please contact your Braze account executive or Customer Success Manager. Note that this option will impact data usage.

  2. Within and Beyond 30 days: To cover both short-term and long-term event property segmentation, you can use Segment Extensions. This feature enables you to segment based on custom events and event properties tracked within the past year. Note that this option will not impact data usage.

Braze’s Success and Support teams can help recommend the best approach depending on your specific needs.

New Stuff!