Skip to content

Braze Learning courseCustom events

This article describes custom events and properties, segmentation, usage, Canvas entry properties, where to view relevant analytics, and more. To learn more about events in Braze, refer to 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.

Use cases

Some common custom event use cases include:

  • Trigger a campaign or Canvas based on a custom event using action-based delivery.
  • Segment users by how many times they performed a custom event, when the last time the event occurred, etc.
  • Use dashboard custom event analytics to view an aggregate of how often each event occurred
  • Find additional analytics using funnel and retention reports.
  • Leverage persistent entry properties to use metadata from your customer event for personalization in your Canvas steps.
  • Generate more sophisticated analytics with Currents.
  • Set up Canvas exception events to define when users should not advance to the next step of your Canvas.

Managing custom events

To create and manage custom events in the dashboard, go to Data Settings > Custom Events.

You can view, manage, create, or blocklist existing custom events on this page. Select the menu next to a custom event for the following actions:


Custom events can be blocklisted individually via the actions menu, or up to 10 events can be selected and blocklisted in bulk. If you block a custom event, no data will be collected regarding that event, existing data will be unavailable unless reactivated, and blocklisted events will not show up in filters or graphs. In addition, if the event is currently referenced by filters or triggers in other areas of the Braze dashboard, a warning modal will appear explaining that all instances of the filters or triggers that reference it will be removed and archived.

Adding descriptions

You can add a description to a custom event after it’s created if you have the Manage Events, Attributes, Purchases user permission. Select Edit description for the custom event and input whatever you like, such as a note for your team.

Viewing usage reports

The usage report lists all the Canvases, campaigns, and segments using a specific custom event. This list does not include uses of Liquid.

You can view up to 10 usage reports at a time by selecting the checkboxes next to the respective custom events and then selecting View usage report.

Logging custom events

Custom events require additional setup. The following lists 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.

Expand for documentation by platform

Custom event storage

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

Segmentation filters

The following table shows the filters available for segmenting users by custom events.

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)


Braze notes the number of times these events have occurred as well as the last time they were performed by each user for segmentation. You can view these analytics at Analytics > Custom Events Report.

On the Custom Events Report page in the dashboard, you can view in aggregate how often each custom event occurs and by segment over time for more detailed analysis. This is particularly useful for viewing how your campaigns have affected custom event activity by looking at the gray lines Braze overlays on the time series indicate the last time a campaign was sent.

Custom event counts graph on the Custom Events page in the dashboard showing trends for a custom event

You can also use Filters to break down your custom events by hour, monthly average users (MAU), segments, or KPI formulas.

Custom event graph filters

Custom events analytics not showing?

Segments created with custom event data cannot show previous historical data from before they were created.

Custom event properties

Custom event properties are custom event metadata or attributes that describe a specific occurrence of an event. These properties can then be used for further qualifying trigger conditions, increasing personalization in messaging, tracking conversions, and generating more sophisticated analytics through raw data export.

Custom event properties are not stored on the Braze profile and, therefore do not consume data points (see Data points below for exceptions).

Expected format

The property 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.
Nested objects Objects that are inside of other objects. For more, see the section in this article on Nested objects.

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

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

Using custom event properties

Custom event properties can be used to qualify campaign triggers, track conversions, and personalize messaging.

Trigger messages

Use custom event properties to narrow your audience further for a particular campaign or Canvas. For example, if you have an ecommerce application and want to send a message to a user when they abandon their cart, you could improve your target audience and allow for increased campaign personalization by adding a custom event property of cart value.

Custom event property filters for an abandoned card. Two filters are combined with an AND operator to send this campaign to users who abandoned their card with a cart value between 100 and 200 dollars

Nested custom event properties are also supported in action-based delivery.

Custom event property filters for an abandoned card. One filter is selected if any items in the cart have a price more than 100 dollars.

Personalize messages

You can also use custom event properties 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.

For example, if you have a gaming application and want to send a message to users who have completed a level, you could further personalize your 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}}}.

Considerations with filters
  • API calls: When making API calls and using the “is blank” filter, a custom event property is considered “blank” if excluded from the call. For example, if you were to include "event_property": "", then your users would be considered “not blank”.
  • Integers: When filtering for a number custom event property and the number is very large, don’t use the “exactly” filter. If a number is too large, it may be rounded at a certain length, so your filter won’t work as expected.


Event property segmentation allows you to target users based on custom events taken and the properties associated with those events. This feature adds more filtering options when segmenting purchase and custom events.

Event properties for custom events are updated in real-time for any segment that uses them. You can manage properties from the Data Settings > Custom Events page by clicking Manage Properties for your custom event. Custom event properties used in certain segment filters have a maximum look-back history of 30 days.

These segmentation filters include:

  • Has done a custom event with property A with value B, X times in the last Y days.
  • Has made any purchases with property A with value B, X times in the last Y days.
  • Adds the ability to segment within 1, 3, 7, 14, 21, and 30 days.

Data is only logged for a given event property after it has been enabled by your customer success manager—event properties are only available from that date moving forward.

Data points

In regards to subscription usage, custom event properties enabled for segmentation with the following filters are all counted as separate data points in addition to the data point counted by the custom event itself:

  • X Custom Event Property in Y Days
  • X Purchase Property in Y Days

Canvas entry properties and event properties

You can leverage canvas_entry_properties and event_properties in your Canvas user journeys. Check out Canvas entry properties and event properties for more information and examples.

Canvas entry properties are the properties you map for Canvases that are action-based or API-triggered. Note that the canvas_entry_properties object has a maximum size limit of 50 KB.

For Canvas Flow messaging, canvas_entry_properties can be used in Liquid in any Message step. Use this Liquid when referencing these properties: canvas_entry_properties.${property_name}. Note that the events must be custom events or purchase events to be used this way.

Use case

Consider the following request for RetailApp, a retail store: \"canvas_entry_properties\" : {\"product_name\" : \"shoes\", \"product_price\" : 79.99}. They can add the word “shoes” to a message with the Liquid {{canvas_entry_properties.${product_name}}}.

RetailApp can also trigger specific messages to send for different product_name properties in a Canvas that targets users after they’ve triggered a purchase event. For example, they can send different messages to users who purchased shoes and users who purchased something else by adding the following Liquid into a Message step.

{% if  {{canvas_entry_properties.${product_name}}} == "shoes" %}
  Your order is set to ship soon. While you're waiting, why not step up your shoe care routine with a little upgrade? Check out our selection of shoelaces and premium shoe polish.
{% else %}
  Your order will be on its way shortly. If you missed something, you have until the end of the week to add any additional items to your cart and enjoy storewide discounts. 
{% endif %}

Expand for original Canvas editor

As of February 28, 2023, you can no longer create or duplicate Canvases using the original editor. This section is available for reference only.

For the Canvases built with the original editor, canvas_entry_properties can be referenced only in the first full step of a Canvas.

Event properties refer to the properties you set for custom events and purchases. These event_properties can be used in campaigns with action-based delivery and Canvases.

In Canvas Flow, custom event and purchase event properties can be used in Liquid in any Message step that follows an Action Paths step. Make sure to use {{event_properties.${property_name}}} if referencing these event_properties. These events must be custom events or purchase events to be used this way in the Message component.

In the first Message step following an Action Path, you can use event_properties related to the event referenced in that Action Path. These event_properties can only be used if the user actually took the action (didn’t go to the Everyone Else group). You can have other steps (that are not another Action Paths or Message step) in between this Action Paths and the Message step.

Expand for original Canvas editor

As of February 28, 2023, you can no longer create or duplicate Canvases using the original editor. This section is available for reference only.

For the original Canvas editor, event_properties can’t be used in scheduled full steps. However, you can use event_properties in the first full step of an action-based Canvas, even if the full step is scheduled.

Nested objects

You can use nested objects (objects inside of another object) to send nested JSON data as properties of custom events and purchases. This nested data can be used for templating personalized information in messages, triggering message sends, and segmentation.

To learn more, refer to our dedicated article on Nested objects.

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, 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 two years. Note that this option will not impact data usage.

Contact your Braze customer success manager for recommendations on the best approach depending on your specific needs.

New Stuff!