
An onboarding checklist in Braze is assembled from four documented parts. A Content Card shows each task, a removal event clears it when the task is done, a custom attribute records the user's stage, and a Canvas reminds and exits users. This post explains how they fit together and what to set on each.
Key Takeaways
- An onboarding checklist in Braze is assembled from Content Cards, removal events, a custom attribute and a Canvas.
- A launched card can't be edited, so finished tasks leave through a removal event instead of showing a tick.
- Content Cards remain available for up to 30 days, and each user can have up to 250 non-expired cards.
- An Action Paths step routes a user by the first action they take, with an evaluation window of up to 31 days.
- Exit criteria mark a user to leave immediately, but a user in a Delay step leaves when the delay ends.
- Agree the removal event names between developers and marketers before anyone builds a card.
What does an onboarding checklist in Braze actually consist of?
The Braze documentation describes four parts, and the checklist is what you get when you wire them together. Content Cards hold the tasks, removal events clear them, a custom attribute records where each user stands, and Canvas decides who hears what next. The Content Cards page points the same way, suggesting you "save outstanding onboarding tasks in a dedicated onboarding tab powered by Content Cards".
The table maps each job to the part that does it.
| Job | Braze part | What the documentation says |
|---|---|---|
| Show one task | Content Card | The data payload for a single card cannot exceed 2 KB after Liquid is rendered |
| Clear a finished task | Removal event on the campaign or Canvas step | Specify a removal event; the card leaves the feed when the user performs it |
| Record the stage | Custom attribute | Suited to lifecycle stages such as onboarding stage |
| Nudge users who stall | Action Paths step | The maximum evaluation window is 31 days |
| Stop messaging finishers | Exit criteria | Users who perform the exception event are marked to exit |
How many tasks should one checklist hold?
Each user can have up to 250 non-expired Content Cards in their feed, and dismissed cards count towards that number. The limit won't be your constraint. A checklist runs out of attention long before it runs out of space.
As a Braze implementation partner, we recommend four to six tasks, with anything beyond that moved into a later Canvas. One card per task matters more than the count. A launched card can't be edited, so a card can't show a tick.
A card can only be removed, which makes the checklist a list of what is still to do. If your design needs a visible tick, plan that with your developers in the app's own interface.
Keep the copy on each card short. If you personalise with Liquid, remember the 2 KB limit applies after rendering. A card over the limit is aborted at send time.
How does a task card disappear when the user finishes the task?
You specify a removal event on the campaign or Canvas step. When the user performs that event, Braze processes it and then removes the card from their feed. You can list several custom events and purchases against one card.
The documentation gives a close parallel. A card prompting a user to complete their profile should be removed as soon as a profile_completed event is logged.
On supported SDK versions, the removal reaches the device during the current session. On earlier versions it may take several minutes and more than one feed refresh.
Braze announced real-time delivery for Content Cards on 15 Oct 2026. Check your SDK versions against the current docs before you promise an instant removal.
The removal event is a contract between your developers and your marketers. Agree the event names before anyone builds a card, and check them in Data Settings before launch. Braze notes that custom attribute keys are case-sensitive, and we apply the same suspicion to event names.
If your team wants help agreeing those event names, the CustomerIK Braze services page describes support for onboarding and technical integration.
What happens to the checklist after 30 days?
Content Cards remain available for up to 30 days from when they are sent, and after that Braze removes them from user feeds. A user who hasn't finished onboarding by then loses the checklist, whether or not you wanted that.
For journeys that need to last longer, the documentation points to Banners, which are designed for persistence and have no mandatory expiration date. Decide the checklist's intended life first, then choose the channel. If activation takes a few days, a card fits, and if it takes weeks, plan the handover to Banners or another Canvas.
Pinning needs one decision. Braze displays a pinned card at the top of the feed. The user can't dismiss it, and the pinned status never changes for the life of the card.
We recommend pinning only the task that gates the others, so users can tidy the rest of their list.
How do you nudge users who stall without double messaging?
Place an Action Paths step after the card message. It holds users for an evaluation window, which is one day by default and can be set up to 31 days.
A user who performs a trigger event advances through that action group. A user who doesn't advances through the default Everyone Else group when the window ends.
One documented detail shapes checklist design: if a user performs a second action matching a different group, they do not switch paths.
The first action decides the route. A single step is therefore built for "did this person do anything?". Per-task questions are better handled with one step per task or a filter on the stage attribute.
Turning on ranking holds everyone until the window ends, then sends each user down the highest priority group they qualify for. That suits a "which reminder fits best" decision. Don't change the setting after launch.
How do you stop messaging users who have finished?
Add exit criteria in the Target Audience step, with an exception event such as the final task's custom event. When a user performs it, Braze marks them to exit immediately and they don't advance to any later steps. Exception events also apply while a user is waiting in a Delay step.
A user in a Delay step stays there until the delay ends, then leaves. Your Canvas analytics can therefore show the exit later than the event, which is expected behaviour.
The documentation also says array attributes aren't currently supported as exit criteria on exception events. Store checklist progress in a simple attribute or an event, not in an array, so the exit rule has something it can evaluate.
How should you record the onboarding stage?
Use both a custom attribute and a custom event. Braze lists lifecycle stages such as onboarding stage as a common custom attribute use. An attribute change can also trigger an Action Paths group, including the first time a value is added to a profile.
The documentation is equally clear that Braze doesn't store time-series information for custom attributes. You can't graph them the way you can graph custom events.
The attribute tells you where a user is now, and the event tells you when and how often. Log the event for measurement and set the attribute for targeting.
What does this look like for a hypothetical subscription app?
Take a hypothetical subscription app with four setup tasks: confirm the email address, allow notifications, choose interests and complete a first action. This is an illustration, not client work, and it contains no results.
At sign-up, a Canvas sends four Content Cards, one per task, with card creation set to first impression, which Braze recommends. Each card has a removal event matching the event the app logs when its task is done. Only the email card is pinned, because the other tasks depend on it.
An Action Paths step follows with a short window. One group triggers on any task event and moves the user on. The Everyone Else group sends a reminder through a second channel.
A user who never opens the app can't see a card, so the reminder can't depend on one. A user who completes two tasks in one session still sees both cards vanish, because each card has its own removal event. The Action Paths step routes them by the first task.
Exit criteria use the final task's event. A closing Delay step is a place to check for late exits in the analytics.
How does this connect to the rest of the programme?
A checklist is one piece of a wider onboarding build. Our guide to onboarding entry, exit and QA covers the rules that sit around it. The step-by-step onboarding workflow shows the Canvas skeleton you would hang the checklist on.
To judge whether the checklist works, read our post on onboarding metrics in Braze. When a task is time-sensitive, pair the card with a push notification for onboarding completion. The post on action-based and API-triggered messages explains the triggers behind removal and reminders.
Our in-app messaging ideas cover the permissionless channel that sits next to cards. For Content Cards in a larger programme, our case study on a multi-brand rewards programme migration describes Content Cards used for gamification and feedback.
What should you test before launch?
Cards behave differently in test sends than in production, so test deliberately.
- Confirm that every removal event and exit event matches the name the app or back end logs, character for character.
- Send tests to a device with push enabled, because test sends deliver the card in the push payload.
- Check your longest personalised card against the 2 KB limit. Test sends can display a card that exceeds it, but production aborts the send.
- Complete the tasks in different orders and confirm each card disappears.
- Put a test user in a Delay step, trigger the exit event and confirm they leave when the delay ends.
- Re-read the volatile limits on the Braze pages in the week you launch.
As a Braze implementation partner, CustomerIK recommends treating the removal event list as the first deliverable of any checklist build. Marketing and engineering should both sign it off before a single card is designed.
Frequently Asked Questions
1. Can a Braze Content Card show a tick when a task is done?
A launched card can't be edited, so a tick isn't something you change on the card. The pattern is to remove the card with a removal event, or to plan a visible tick in your app's own interface.
2. How long does an onboarding checklist card last?
Content Cards remain available for up to 30 days from when they are sent. Banners are the documented option for messages that need to persist longer.
3. How many Content Cards can one user hold?
Each user can have up to 250 non-expired Content Cards in their feed. Dismissed cards count towards that limit.
4. Is card removal instant?
Not necessarily. On supported SDK versions the removal reaches the device during the current session. On earlier versions it may take several minutes and more than one feed refresh.
5. Do exit criteria remove a user from a Delay step straight away?
Braze marks the user to exit immediately. A user in a Delay step stays there until the delay period ends and then leaves instead of advancing.
Sources
- Braze, Create a Content Card. Retrieved 12 Nov 2026.
- Braze, Content Cards. Retrieved 12 Nov 2026.
- Braze, Action Paths. Retrieved 12 Nov 2026.
- Braze, Exit criteria. Retrieved 12 Nov 2026.
- Braze, Custom attributes. Retrieved 12 Nov 2026.
- Braze, Release notes, entry "Real-time updates for Content Cards" dated 15 Oct 2026. Retrieved 12 Nov 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 checklist needs an agreed set of removal events before the first card is built, let's talk.




