If you’ve ever tried to send a push notification or email campaign that actually gets results, you know that “spray and pray” marketing is dead. Segmentation is how you get your message to the right people, and custom attributes are where the magic happens in Braze.
This guide is for marketers, product managers, and anyone wrangling Braze who wants to use custom attributes for segmentation that’s real-world useful—not just “because the docs said so.” I’ll break down what works, what doesn’t, and how to avoid making a mess you’ll regret later.
Why custom attributes matter (and where people go wrong)
Default attributes in Braze—like email, signup date, or push opt-in status—are fine for basic stuff. But if you want to target users based on actual behavior or traits, you need custom attributes. Think subscription tier, favorite product category, or whether someone has seen a particular feature.
Here’s the catch:
Custom attributes are powerful, but easy to overdo. If you try to track everything, you end up with a bloated, messy dataset that nobody trusts. If you track too little, your segments will be uselessly broad.
Common mistakes to avoid: - Creating attributes you never use (“Has completed onboarding step 13”...and then never referencing it again) - Storing the same data in multiple places (e.g., both a custom attribute and an event property) - Picking attribute names that make sense to you, but not to anyone else
Step 1: Decide what actually matters for segmentation
Before you go wild adding attributes, get clear on what segments you’ll really use. Talk to your marketing team, product folks, or whoever’s running campaigns. Ask:
- What user behaviors do we want to target? (e.g., “Users who purchased in the last 30 days”)
- What profile traits actually change messaging? (e.g., “Is a paid subscriber”)
- Are there business rules we need to encode? (e.g., “Region,” “Industry,” “On free trial”)
Pro tip:
If you can’t imagine creating a campaign or report with an attribute, don’t add it.
Stuff you can safely ignore: - Super granular tracking (“Clicked menu item X”) unless you’re really personalizing at that level - Anything that can be derived from existing events or attributes (avoid duplication)
Step 2: Name custom attributes clearly (you’ll thank yourself later)
Attribute names in Braze are case-sensitive and can’t be changed once set. That means you need to get it right up front.
Best practices:
- Use snake_case or camelCase, and stick to one convention (don’t mix and match)
- Make names descriptive but not novel-length: is_premium_user, last_purchase_date, favorite_category
- Avoid abbreviations only your team understands (usr_lvl = bad, user_level = good)
- Add units if it matters: avg_order_value_usd instead of avg_order_value
What doesn’t work:
Don’t use vague names like status or flag. Six months from now, nobody will remember what they mean.
Step 3: Keep data types consistent
Braze supports strings, numbers, booleans, arrays, and dates for custom attributes. If you mix types for the same attribute (say, sometimes a string, sometimes a boolean), you’ll have a segmentation headache.
Do:
- Use booleans for yes/no (is_subscribed)
- Use ISO date strings or Unix timestamps for dates
- Use numbers for counts or currency (but always clarify units)
- Use arrays for lists (like favorite genres)
Don’t: - Overuse strings when a boolean or number would be cleaner - Switch data types mid-stream (the old “0/1” vs. true/false problem)
Step 4: Set and update attributes reliably
How you set custom attributes depends on your setup—SDKs, APIs, or integrations. The main thing is to make sure they’re up-to-date and don’t get out of sync.
Checklist: - Make sure attributes are set at the right time (e.g., after a purchase, not just on signup) - Clear attributes if the value is no longer relevant (set to null or remove, don’t leave stale data) - Keep your data pipeline simple. Don’t try to sync every detail from your database—just what matters for messaging. - Test with real user profiles before rolling out new segments
What to watch for:
If your data team is piping in attributes from a data warehouse, double-check update frequency. Stale data = bad segments.
Step 5: Build segments that are actually useful
Once your attributes are clean, segmentation in Braze is straightforward. But it’s easy to get lost building segments nobody will ever use.
Good segment examples: - Users who’ve made a purchase in the last 30 days and are not premium - Free trial users who haven’t completed onboarding - Lapsed users who used to buy monthly, but haven’t in 60+ days
Skip segments like: - “Users created between 7 and 8 days ago and who clicked one specific button” (too narrow, probably useless) - Segments with 5+ filters that only return a handful of users
Pro tip:
Start with broad segments and only get more granular if you see a clear need (like a campaign that’s actually going to those people).
Step 6: Audit and clean up regularly
Your user base changes, so should your attributes and segments. Every few months, do a quick audit:
- Are there attributes nobody is using? Archive or remove them.
- Are any attributes always null or default? Figure out if they’re broken.
- Do your segments still match your actual campaigns?
- Is there duplicate info (like both
is_premiumandsubscription_status)?
What to ignore:
Don’t feel like you have to “use” every attribute just because it exists. If it’s not helping, kill it.
Step 7: Document for your future self (and your team)
You don’t need a 20-page wiki, but basic documentation saves everyone’s sanity.
- Keep a simple doc or spreadsheet listing each custom attribute, what it means, and where it’s set
- Add examples of how attributes are used in real segments
- Note any quirks (“this attribute is only set for mobile users”)
Why bother?
You (or someone else) will forget. Docs keep things honest and prevent accidental misuse.
What actually works (and what’s just hype)
Works: - Focusing on a small set of high-impact attributes - Keeping naming and data types consistent from day one - Regularly cleaning up old attributes and segments - Building segments around real campaigns, not hypotheticals
Doesn’t work: - Tracking everything just because you can - Overcomplicating segments with endless filters - Letting attributes go stale or undocumented
Ignore: - “AI-driven” segmentation until your basics are solid. Most value comes from clear, human-thought-out segments.
Keep it simple, iterate often
You don’t need a thousand custom attributes to get results from Braze. Start with the basics, only add what you’ll actually use, and revisit your segments every so often. Clean data and clear naming will save you way more headaches than any fancy segmentation tricks.
Remember: simple, actionable segments beat “clever” ones every time. If you’re not sure where to start, pick one key attribute, build a segment, and see what happens. The rest will follow.