.svg)
Braze feature flags let you switch a feature on or off for chosen users without shipping new code or waiting for an app store update. A flag can be driven by a rollout percentage, a Canvas step or an experiment. Choosing one controlling surface per flag, and agreeing who owns it, is what keeps releases predictable.
Key Takeaways
- A feature flag separates shipping code from releasing the feature, so product and marketing teams can control exposure from the dashboard.
- Give each flag one controlling surface: the rollout slider, a Canvas Feature Flag step or a feature flag experiment.
- Rules are evaluated from top to bottom, and a user qualifies for the first rule they meet.
- Entry to a Canvas step overrides the default rollout configuration, so a rollout and a Canvas on one flag can disagree.
- Experiments need impressions logged, support up to nine groups, and exclude users in the Global Control Group.
- Flags refresh at session start, and manual refreshes are rate limited to once every five minutes (subject to change), so avoid them for critical, time-sensitive updates.
What do Braze feature flags change about a release?
A feature flag separates two events that usually happen together: the code reaching devices and the feature reaching users. Braze describes the result as being able to turn a feature on and off in production without additional code deployment or app store updates.
That changes who can act. Engineers ship the code once, behind a flag that is off. Product and marketing teams then decide who sees it and when, from the dashboard.
By default a flag is inactive, which lets you separate the release date from user activation. Treat that default as the main feature. It gives the launch a calendar of its own.
Which control surface should own each flag?
A flag can be enabled in three places: the rollout slider, a Canvas Feature Flag step, or a Feature Flag experiment. Each answers a different question, and the choice shapes everything that follows.
| Control surface | Best for | What to watch |
|---|---|---|
| Rollout percentage and rules | Engineering-led gradual release to a segment | Keep it out of flags that Canvas or an experiment also enable |
| Canvas Feature Flag step | Product and marketing sharing one audience and one message | Entry to the step overrides the default rollout configuration |
| Feature Flag experiment | Measuring the effect of the feature on conversions | Needs impressions logged, and Global Control Group users are excluded |
Braze lets you add a description to a flag, and the documentation notes it can answer questions others have when browsing flags.
Our view is that the description should name three things before launch: the owner, the condition for switching the flag off, and the surface that controls it. A flag with no named owner is the one nobody dares to switch off.
How do multi-rule rollouts decide who gets a flag?
Rules are evaluated from top to bottom, in the order they're listed. A user qualifies for the first rule they meet. If they meet none, the default "Everyone Else" rule decides.
That order makes the rule list a piece of design work. Put narrow, high-confidence audiences first, such as internal testers, and broader audiences below them. Leave "Everyone Else" off until you have a reason to turn it on.
The documentation describes the "Everyone Else" rule as a default. If it is toggled off, a user who meets no other rule won't receive the flag at their session start.
Why shouldn't you combine a rollout with a Canvas or an experiment?
To avoid users being enabled and disabled by different entry points, Braze says to pick one route. Either set the rollout slider above zero, or enable the flag in a Canvas or experiment. If a Canvas or experiment will use the flag, keep the rollout at zero.
The reason is how the surfaces interact. Entry to a Canvas step overrides the default rollout configuration, so a Canvas can enable a flag for a user who doesn't qualify for the rollout. Two controllers can then disagree about one person.
One failure mode to plan for starts with a flag that begins as a rollout. It is later wired into a Canvas without the slider being reset. Nobody changed the audience, yet the audience is no longer what anyone thinks it is.
The fix is procedural. When a flag moves to a new controlling surface, reset the old one first and check a test profile in the Feature Flags Eligibility tab.
How do you coordinate product and marketing with a feature flag Canvas?
Braze suggests using feature flags to synchronise a feature's rollout and its messaging. In its example, the rollout stays at zero. A Canvas Feature Flag step enables the flag for a target segment, and messaging follows automatically.
This works because the audience is defined once. The people who can see the feature are the people who receive the announcement. Our guide to automating complex workflows in Braze Canvas covers the Canvas side in more depth.
Two documented behaviours deserve a place in your runbook:
- If a user enters two Canvases that reference the same flag, they receive the value from the Canvas they entered last.
- When a Canvas is stopped, archived or has the step removed, users who passed through that step no longer receive the flag or its properties.
The second point matters at handover. Suppose a Canvas controls a flag and you stop it. Users who relied on that step lose the feature unless a rollout, an experiment or another Canvas still covers them.
What does a feature flag experiment need from your app?
An experiment compares groups, so the app has to report who saw what. Braze asks you to log a feature flag impression whenever a user sees or could have seen the feature, including users in the control group. Impressions are logged once per session.
An experiment supports up to nine groups: one control plus up to eight variants. Braze also advises against changing the distribution after launch.
Our advice is to resist adding variants mid-test, because the comparison is only as clean as the split.
The conversion events you choose need to exist before launch. If your event model is patchy, start with our guide to tracking user events in Braze. For the testing mindset itself, our post on A/B testing email campaigns in Braze applies the same discipline to a different channel.
One more documented point: users in the Global Control Group can't have feature flags enabled, so they can't be part of feature flag experiments. If you rely on holdouts elsewhere, our guide to measuring Decisioning Studio with a holdout group is a useful reference for keeping comparisons honest.
How fresh is a flag on the device?
Flags refresh automatically at session start and when the active user changes. They can also be refreshed manually, and Braze documents that refreshes are rate limited to once every five minutes, which is subject to change. The SDK caches the values, so they remain available offline.
Braze recommends refreshing manually only before an important user action, such as loading a checkout page. Beyond that, plan for flags to change at the next session start.
Braze also points out that flags rely on device connectivity to sync, and recommends avoiding these channels for critical, time-sensitive updates. A flag is therefore a good tool for a staged release and a poor one for an action that must land at an exact moment.
Mid-session changes need a decision from your app team. Braze notes that you may not want to re-render the interface when a flag changes, to avoid a shocking change in how it looks. The recommended pattern is to listen for flag updates and decide which changes should re-render.
Newer SDK versions add an event subscription that replaces the earlier update subscription. Braze documents this for Web SDK 7.0.0 and later and Android SDK 44.0.0 and later, so check which one your apps use.
What should you settle before you create the first flag?
Four facts are worth settling early, because each is awkward to change afterwards.
| Decision | Documented fact | Why it matters |
|---|---|---|
| Flag ID | The ID cannot be changed later | Agree a naming convention before the first flag exists |
| Property payload | Properties are limited to a total of 10,000 characters | Keep large content in your own systems and pass references |
| SDK initialisation | Flags can't be used to limit which users are created or tracked in Braze | Handle consent and tracking decisions separately |
| Active flag count | Plan limits are 10 active flags per workspace on the free version and 110 on the paid version | A flag counts as active while its rollout is above zero or it sits in an active Canvas or experiment, so wind down finished flags |
On naming, Braze suggests a behaviour, product and feature pattern. Keep the behaviour disabled by default in your code, and avoid phrases like "disabled" in the name.
A flag called show_loyalty_tier_banner reads clearly. One called disable_old_banner invites double negatives at three in the morning.
We would also settle one question outside Braze: who is allowed to change a flag in production. A flag is a production switch, and it deserves the same change discipline as a deployment.
The SDK point touches personal data. Whether and how users are tracked is a consent matter for your legal and security teams, and this post does not settle it.
How would a hypothetical retailer sequence a loyalty launch?
Take a hypothetical retailer launching a loyalty tier in its app. The figures are deliberately absent: this is an illustration of order, not a record of any real programme.
- The team creates a flag with a clear ID and a description naming the owner and the switch-off condition. The rollout stays at zero.
- The app ships with the flag read in code, the loyalty screen hidden by default, and an event subscription so a changed flag updates the screen sensibly.
- A Canvas Feature Flag step enables the flag for an internal testers segment. The team checks eligibility on a test profile and confirms the screen appears.
- The Canvas is widened to the launch segment, and the same Canvas sends the announcement. Product and marketing now share one audience definition.
- Before the Canvas is stopped, the team decides what covers those users afterwards. Stopping the step removes the flag from users who relied on it, so the handover is tested on a small segment first.
- Once everyone has upgraded and the option to disable is no longer needed, the team removes the flag from the code and archives it.
The fifth step is the easiest to skip. The launch feels finished once the announcement lands, but the handover is where a feature changes state without anyone clicking anything. Planning it in advance costs an afternoon, while discovering it live costs a weekend.
How does this connect to the rest of your Braze programme?
Flags work best when audiences are shared rather than rebuilt. Braze lets you filter segments and message audiences by whether a user has a flag enabled, and it blocks segments that reference other flags to prevent recursion. Our post on segmenting your audience for better engagement in Braze covers how to keep those definitions tidy.
On the engineering side, flags are one of several ways developers can extend what Braze does. Our overview of how developers can extend Braze functionality shows where flags sit alongside the others.
As a Braze implementation partner, CustomerIK recommends giving every flag one controlling surface, one named owner and a written handover plan before the first user is enabled.
Frequently Asked Questions
1. Can a feature flag go to a small group of users first?
Yes, you can. Create a segment for those users and enable the flag for all of that segment. Braze documents this approach for targeting by email address, user ID or any profile attribute.
2. What happens to users when the rollout percentage changes?
Rollouts stay consistent across devices and sessions. Raising the percentage keeps the existing group enabled and adds new users, and lowering it keeps only the original group.
3. Does a feature flag stop the Braze SDK from tracking users?
No, it doesn't. The SDK must be initialised to download and synchronise flags for the current user, so flags can't be used to limit which users are created or tracked.
4. Are flags available when a user is offline?
Yes, they are. After a refresh, flags are stored on the device and can be read offline. Braze advises against relying on flags for critical, time-sensitive updates.
5. How often can the SDK refresh flags?
Flags refresh at session start and when the active user changes, and manual refreshes are rate limited to once every five minutes, subject to change. Check the current documentation before depending on this.
Sources
- Braze, Feature flags. Retrieved 26 Oct 2026.
- Braze, Create feature flags. Retrieved 26 Oct 2026.
- Braze, Feature flag experiments. Retrieved 26 Oct 2026.
- Braze, Feature flags FAQ. Retrieved 26 Oct 2026.
- Braze, Feature Flag Canvas step. Retrieved 26 Oct 2026.
- Braze, Release notes. Retrieved 26 Oct 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 you are planning a flag-based release and want a second view on who controls what, let's talk.
.svg)
