.svg)
Braze user event tracking decides what your campaigns can do later. Event names and properties become the dropdown a marketer reads two years from now, and the filters every segment depends on. Braze publishes a naming structure, property limits and reserved keys. Getting those right at instrumentation costs an afternoon. Getting them wrong costs a migration.
Key Takeaways
- Braze describes custom events as best suited to high-value interactions, so each event you add is something a marketer has to understand.
group_noun_actionis the most common naming structure, and Braze says event names should all be lowercase.- Tag one event and use properties for differences such as channel, rather than creating one event per variant.
- Each custom event or purchase can carry up to 256 distinct properties, and some keys are reserved.
- Property data is logged only after you enable it for segmentation, and it's available only from that date forward.
- Blocklisting an event stops new data being processed and archives any segment, campaign or Canvas that uses it.
What does Braze user event tracking actually record?
Braze describes custom events as actions taken by, or updates about, your users, and says they're best suited to tracking high-value interactions within your app. Logging one can trigger campaigns and support segmentation.
The high-value part is the design constraint. Custom events aren't a general telemetry pipeline. Each one becomes a row in a dashboard list, a segmentation filter and a possible trigger, so every event you add is something a marketer has to understand.
Braze states that there is no fixed dashboard cap on how many distinct custom events or custom attributes you can define. No cap isn't the same as no cost, because every addition makes the list harder to read.
How should you name Braze custom events?
Braze names group_noun_action as the most common naming structure, and says event names should all be lowercase to avoid casing instrumentation errors.
Its naming guidance is short enough to put straight into a spec. The right-hand column is our reading of what goes wrong without each rule.
| Rule from Braze | Where it bites |
|---|---|
| Keep your naming convention clear | A marketer choosing from the dropdown can't tell which event they want |
| Use consistent casing and formatting of event names | Casing differences produce instrumentation errors |
| Avoid giving events similar names | A campaign triggers on the wrong event and reaches the wrong audience |
| Avoid long event attribute strings | Braze notes they are truncated or cut off in the dashboard |
Braze gives examples too. user_signup and newsletter_subscribed are clear, and signup_event_1 doesn't tell you what is being tracked.
There's a hard limit underneath the style guidance. Braze enforces a limit of 479 bytes for custom event names, custom attribute names and custom event string values, and recommends keeping names and values to 50 characters where possible.
When should you use a property instead of a new event?
Braze's advice is to tag one event and identify differences with properties. It uses the example of events that are the same apart from a minor detail, such as the channel.
The reason to care is combinatorial. One event with three properties stays one row in the dashboard. Three events, each named for a variant, become three rows, three filters and three things to keep in step when the product changes.
Each custom event or purchase can have up to 256 distinct custom event properties. Property keys are strings of 255 characters or fewer with no leading dollar sign.
Some keys are reserved. On custom events they are time and event_name. On purchase events the reserved set is larger: time, product_id, quantity, event_name, price and currency. Braze returns an invalid properties error if you use one, so catch it in code review rather than in staging.
What are the limits that catch teams out?
Three documented behaviours change what a taxonomy can do after the fact, and all three concern history rather than capacity.
Event property data is logged only after you enable it for segmentation, and it's available only from that date moving forward. Segments created with custom event data can't show historical data from before the segment existed. Custom event properties used in certain segment filters also have a maximum look-back of 30 days.
Put together, they mean instrumentation isn't retroactive. A property you enable today answers questions about next quarter, not last quarter.
Profile-level metadata behaves differently, and it's worth separating in your own documentation. Custom event metadata on the profile (first or last occurrence, total count, and X in Y over 30 days) is retained indefinitely for as long as the profile is active.
One more limit shapes rollout order. By default you can have 20 segmentable event properties per workspace, and raising that means contacting your Braze account manager. Treat twenty as a budget, and decide which properties earn a slot before you enable them one at a time.
How do you keep the taxonomy clean once it is live?
Braze provides the tools for governance. The usual gap is that nobody is assigned to use them.
- Find out what uses a property before you change it. The Manage Properties view for an event or product shows which campaigns or Canvases use that property.
- Look for near-duplicate entries in the event list. Braze removes leading and trailing whitespace from the events and attributes it receives, so spelling and casing are the usual suspects.
- Pick one canonical spelling and casing, then update dashboard workflows, imports and runbooks to match it.
- Blocklist the retired entry rather than leaving it in the list.
- Check what depended on it. Braze archives any segment, campaign or Canvas that uses a blocklisted event or attribute.
Blocklisting deserves care before you use it. Data sent for a blocklisted event isn't processed, blocklisted events no longer count as data points, existing data is unavailable unless the event is reactivated, and the event disappears from filters and graphs.
As a Braze implementation partner, our recommendation is to treat the dashboard as a product surface. Someone owns the event list the way someone owns a database schema, and no event ships without a name, a purpose and a named owner.
What changed recently?
The event surface has moved this quarter, so check the release notes before you finalise a spec.
On 17 Sep 2026, Braze added filtering of eCommerce recommended events by their event properties, both basic and nested, in triggers, action paths, conversion events, exit criteria and more.
Two earlier releases matter as well. On 23 Jul 2026, the CSV import flow for custom events gained a mapper, which lets you map event names and event property headers to Braze fields before you import. On 25 Jun 2026, eCommerce recommended events stopped counting toward billable data points.
If you're choosing between a bespoke custom event and a recommended one, that last change belongs in the comparison. Check the data points documentation for how your own contract counts the alternative.
How does event design connect to the rest of your programme?
Events are the entry and exit conditions of your lifecycle work, which is why the naming decisions above echo through every journey. An onboarding journey in Canvas is only as precise as the events that trigger it, and the activation campaigns around it depend on the same list.
Hyper-personalisation and dynamic content draw on the properties you attach, and retention strategies rely on events that mark the moments a user drifts. A clean taxonomy makes each of those cheaper to build and easier to hand over.
Frequently Asked Questions
1. What naming structure does Braze recommend for custom events?
Braze names group_noun_action as the most common naming structure and says event names should all be lowercase.
2. How many properties can one custom event carry?
Up to 256 distinct custom event properties for each custom event or purchase.
3. Which property keys are reserved?
On custom events, time and event_name. On purchase events, time, product_id, quantity, event_name, price and currency.
4. Can I segment on an event property retroactively?
No. Data is logged for an event property only after you enable it, and it's available from that date moving forward.
5. Do custom event properties consume data points?
Braze states that custom event properties aren't stored on the profile and therefore don't log data points.
Sources
- Braze, Event naming conventions. Retrieved 01 Oct 2026.
- Braze, Custom events. Retrieved 01 Oct 2026.
- Braze, Custom event properties. Retrieved 01 Oct 2026.
- Braze, Custom event properties, segmentation limits. Retrieved 01 Oct 2026.
- Braze, About analytics for the Braze SDK. Retrieved 01 Oct 2026.
- Braze, Manage custom data. Retrieved 01 Oct 2026.
- Braze, Blocklist custom data. Retrieved 01 Oct 2026.
- Braze, Release notes, 17 Sep 2026. Retrieved 30 Sep 2026.
- Braze, Release notes, 23 Jul 2026. Retrieved 30 Sep 2026.
- Braze, Release notes, 25 Jun 2026. Retrieved 30 Sep 2026.
- Written by CustomerIK, a Braze implementation partner.
CustomerIK is a Braze implementation partner working across onboarding, technical integration, marketing operations and customer data management.
If your event list has grown faster than anyone can explain it, let's talk.
.svg)
