Braze
Send user data to Braze for engagement campaigns. Sync user attributes, arrays of objects on the profile, custom events, purchases, and more from your warehouse to Braze.
Prerequisites
- A Braze account
- A Braze REST API key with the necessary permissions
- Your Braze REST endpoint (cluster URL)
Authentication
Braze uses REST API Key authentication.
- In Braze, go to Settings > API Keys
- Create a new REST API key with the required permissions (users.track, users.delete, etc.)
- Copy the API key
- Paste it into the REST API Key field in Zeotap
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| REST Endpoint | Select | Yes | Your Braze REST API endpoint for your cluster. Suggestions cover US-01 through US-08 (Braze has no US-09), US-10, EU-01, EU-02, and AU-01. If Braze put you on a cluster that is not listed, choose Enter a custom value and paste the endpoint from Settings → APIs and Identifiers. |
| App Group ID | Text | No | Braze app group identifier (optional) |
| User data endpoint | Select | No | Automatic (default) or /users/track only. How user attributes, custom events and purchases are sent; see Throughput. |
| Max requests per second | Number | No | Caps how fast everything sending to this destination (syncs and realtime syncs), together, calls each Braze endpoint (minimum 1). Leave empty to use up to 80% of each endpoint’s Braze rate limit. |
Target Settings
| Field | Type | Required | Description |
|---|---|---|---|
| Object Type | Select | Yes | The type of data to send: User Attributes, User Attribute: Array of Objects, Custom Events, Purchases, User Delete, User Alias, User Merge, Subscription Status, Catalog Items, Trigger Campaign, or Trigger Canvas |
| Array attribute | Text | Conditional | Array of Objects only: the custom attribute that holds the array, for example permissions |
| Object identifier field | Text | Conditional | Array of Objects only: the mapped field that identifies each object within one user’s array, for example permission_id |
| Catalog Name | Text | Conditional | Catalog name (required for Catalog Items) |
| Campaign ID | Text | Conditional | Campaign ID to trigger (required for Trigger Campaign) |
| Canvas ID | Text | Conditional | Canvas ID to trigger (required for Trigger Canvas) |
| Subscription Group ID | Text | Conditional | Subscription group ID (required for Subscription Status) |
| Audience membership attribute | Text | No | Audience syncs of User Attributes only: the array attribute listing the audiences a user is in. Default audiences. |
| Audience membership value | Text | No | Audience syncs of User Attributes only: the value added and removed for this audience. Default: the audience’s name. |
| Send changed fields only | Toggle | No | Audience syncs of User Attributes in Mirror or Upsert mode only. See Send changed fields only. Default: Off. |
Supported Operations
Sync Modes: Upsert, Insert, Mirror
Mirror is for User Attribute: Array of Objects, where a row that leaves the model removes its object from the array (see Arrays of objects). For the other object types the sync never takes anything out of Braze (for most of them that would mean deleting the profile), so on a model sync they leave rows that left the model alone, in every mode. For them, Mirror behaves like Upsert. A row that left is never sent again: not as a second copy of an event or purchase, not as another campaign or Canvas trigger, and never as a deletion.
Arrays of objects
A Braze custom attribute can hold an array of objects , such as a user’s permissions:
"permissions": [
{ "permission_id": "billing", "level": "admin" },
{ "permission_id": "reports", "level": "read" }
]Segments can filter on it (permissions[].level is admin), and Liquid can loop over it in messages. The User Attribute: Array of Objects object type keeps such an array in step with a table that has one row per object. It adds, updates and removes individual objects, so objects the run does not mention are not touched, including any that other systems keep in the same attribute.
Set it up.
- Build a model with one row per object, for example a
permissionstable withuser_id,permission_idandlevel. Add a column that combines the user and the object, for exampleuser_id || ':' || permission_id AS grant_key, and pick it as the sync’s Primary Key Column. The sync detects added, changed and removed rows by this key, so with it every object is exactly one row: moving an object from one user to another arrives as removed from the first and added to the second. A key that is only the object’s own id, or a grant id, can leave an object behind on its previous user. - Choose User Attribute: Array of Objects, set Array attribute (
permissions) and Object identifier field (permission_id). - Map the user’s id to
external_id. Then map every column that should be in the object under the name it should have there, including the identifier field. The form does not require the identifier field, but a row without it fails. - Choose the Mirror sync mode, or Upsert to never remove objects. Insert is refused for this object type, because it sends every row as new on every run, which would add each object to the array again each time.
The user is named by external_id only. Every other mapped field, email and phone included, becomes a field of the object. A row with no external_id fails rather than going to whoever another field names.
What each run does.
| Row in this run | Mirror | Upsert |
|---|---|---|
| Added | Object added ($add) | Object added |
| Changed | Object updated ($update); its fields are merged into the object | Object updated |
| Removed (left the model) | Object removed ($remove) | Left in the array |
How it is sent. All of one user’s changes in a batch go in a single request, as one entry with that user’s $add, $update and $remove operations. Braze processes separate /users/track requests asynchronously and does not guarantee their order, but it applies the operations within one entry in a fixed order, so a user’s changes land together. Each object gets at most one operation per batch. If one row leaves and another arrives with the same identifier for the same user in one run (possible when the key is not user plus identifier), the object is updated in place. Two rows that both add or change the same object for one user fail after the first, because Braze would keep both as separate objects.
One user’s objects can span several batches, and those requests are spaced out. A sync reads rows in no particular order by user, so a user with many objects usually appears in more than one batch. When separate requests for one user overlap at Braze, updates are lost even though every request answers success. Braze advises waiting a few seconds between calls for the same user, so batches of this object type run one at a time, and a batch waits until 3 seconds have passed since any of its users was last written. Syncs of this type therefore take longer than other Braze syncs: up to 3 seconds per batch when batches share users, and no extra time when they do not. The spacing follows Braze’s advice but Braze gives no guarantee, so a heavily loaded workspace could still lose an update to a user whose objects span batches.
- Each request carries up to 75 users.
- A request that adds objects is sent once. It is retried after a
429(Braze processed nothing) but not after a5xxor a timeout, after which Braze may have applied it and a retry would add the objects twice. Those rows are reported failed. Requests that only update or remove objects are retried as usual. - A user who only has updates or removals in a batch is never created in Braze.
- Empty (NULL) values are never sent. Braze discards every nested-attribute update in a request that contains a null anywhere. A new object leaves the empty field out. When a column of an existing row becomes empty, the sync’s change detection carries the column’s previous value, so the object keeps its last value for that field.
- Braze refuses field names with a space, a period or a dollar sign, and names or text values longer than 255 characters, by discarding every nested update in the request. Such a row fails with the reason before it is sent.
- Braze limits one nested attribute to 100 KB and silently drops any update past that. If one user’s additions and updates in a run add up to more than 100 KB, those rows fail and are not sent. That user’s removals still go. The check counts only what the run sends: an array already near the limit in Braze can still have an update dropped.
- Field names are matched to the settings whatever their case, because some warehouses (Snowflake among them) return column names in lower case. The identifier is always sent under the spelling set in Object identifier field.
- The identifier must be a single value (text or a number) on every row. Keep its type the same over time: an object added as the number
7may not match the text"7". - Timestamps are sent as Braze receives them from the warehouse, as text, not as Braze’s
$timedates, so segment on them as text. - Array-of-objects syncs use
/users/trackonly, whatever User data endpoint is set to. - Braze counts a data point for every field sent. An added object costs one per field, and an updated one one per field of the row.
Objects can be duplicated when a row is sent as new for an object Braze already holds, because Braze does not keep identifiers unique. Two kinds of run send rows that way, and neither is used for this object type:
- Adding a field to the sync’s mapping makes the sync resend every row. For this object type, rows it has sent before are resent as updates.
- Warehouse change tracking can resend the whole table as new: a Snowflake stream with nothing pending is recreated to return every row, and BigQuery change history re-snapshots when its window runs out. This object type never uses change tracking; every run compares full snapshots of the model.
Duplicates can still come from a first sync into an attribute that already holds objects, or from a run that stopped part-way and was run again. A later removal of that identifier removes every copy. To start clean, clear the attribute in Braze before the first sync.
An object missing from Braze is not re-created by a change. Braze’s $update does nothing when no object has the identifier, so an object that Braze lost or never received stays missing until its row is removed and added again.
Audience Sync Modes: Add, Remove, Mirror, Upsert
Braze segments are filters, not lists, so an audience sync of User Attributes records membership on the profile. It keeps an array attribute (default audiences) that lists the audiences each user is in. Build the Braze segment as audiences includes VIP.
| Mode | Members | People who leave |
|---|---|---|
| Add, Upsert | Attributes updated, audience added to the array | — |
| Remove | — | Audience removed from the array |
| Mirror | Attributes updated, audience added to the array | Audience removed from the array |
Leaving an audience never deletes the Braze profile. A removal changes only the membership array. It leaves the person’s other attributes, history and subscriptions alone, and never creates a profile for someone Braze doesn’t know. To delete profiles, sync with the User Delete object type. It deletes every row it is sent, so choose it deliberately.
By default the value is the audience’s name. If you rename the audience, its members keep the old name in the array as well. Set Audience membership value to a fixed value if you plan to rename audiences.
For the other object types (events, purchases, triggers and so on), a mirror run sends only the members, not the people who left. A remove run is refused, because those types have nothing to remove.
Membership is recorded by audience syncs only. A journey that sends to Braze updates attributes without touching the membership array, even when its send step names an audience.
Send changed fields only
Turn this on for an audience sync of User Attributes in Mirror or Upsert mode to send Braze less data. Braze keeps every attribute it is not sent.
| Person | What is sent |
|---|---|
| Joins the audience | Every mapped attribute, and the audience is added to the array |
| Stays, and a mapped attribute changed | Their identifiers and only the attributes that changed, and the audience is added to the array again |
| Stays, and a mapped attribute was emptied | Their identifiers and that attribute as empty, so Braze removes it |
| Stays, and nothing mapped changed | Nothing |
| Leaves (Mirror) | Their identifiers, and the audience is removed from the array |
Identifiers are external_id, user_alias, braze_id, email and phone, whichever the mapping sends. The first run, and the first run after you change the field mapping, send every member in full.
Features
- Field Mapping: Yes
- Schema Introspection: No
Required Mapping Fields
Required fields depend on the selected Object Type:
| Object Type | Required Fields |
|---|---|
| User Attributes | external_id |
| User Attribute: Array of Objects | external_id; also map the field named in Object identifier field (not enforced by the form, but every row needs it) |
| Custom Events | external_id, name, time |
| Purchases | external_id, product_id, currency, price |
| User Delete | external_id |
| User Alias | external_id, alias_name, alias_label |
| User Merge | identifier_to_merge, identifier_to_keep |
| Subscription Status | external_id, subscription_state |
| Catalog Items | id |
| Trigger Campaign | external_user_id |
| Trigger Canvas | external_user_id |
Default Destination Fields (User Attributes)
external_id, email, first_name, last_name, phone, gender, dob, country, city, language, time_zone, email_subscribe, push_subscribe
Throughput
Each batch is split into requests of Braze’s maximum size, and many requests are in flight at once (up to 128 per sync). Every endpoint is paced to 80% of its Braze rate limit, so the rest of your Braze workspace keeps some room.
The pacing follows the rate-limit headers Braze returns on every response. If your contract’s limit is higher or lower than Braze’s default, syncs use 80% of your limit. If other traffic is already using the current window (your own backends, another sync, a realtime sync), the sync slows down so that together you stay under the limit, and speeds up again when the window resets. If Braze answers 429, or says the current window is used up, that endpoint pauses until Braze says the window resets, instead of every request in flight hitting the limit separately.
| Object type | Braze endpoint | Per request | Braze limit | Paced at |
|---|---|---|---|---|
| User Attributes, Custom Events, Purchases | /users/track | 75 | 3,000 requests / 3 s | 800 requests/s |
| User Attribute: Array of Objects | /users/track only, one batch at a time | 75 users, all of a user’s changes in one entry | 3,000 requests / 3 s | 800 requests/s, with 3 s between requests for one user |
| … large syncs, also (if your account has it) | /users/track/bulk | 1,000 (max 100 per user), 2 MB | 50 requests/s, separate from /users/track | 40 requests/s |
| User Delete, User Alias, User Merge | /users/delete, /users/alias/new, /users/merge | 50 | 20,000 requests/min, shared | ~266 requests/s |
| Subscription Status | /subscription/status/set | 50 | 5,000 requests/min | ~66 requests/s |
| Catalog Items | PUT /catalogs/{name}/items | 50 | 16,000 requests/min | ~213 requests/s |
| Trigger Campaign, Trigger Canvas | /campaigns/trigger/send, /canvas/trigger/send | 50 recipients | 250,000 requests/hour, shared | ~55 requests/s |
User Merge requests are sent one at a time, in order, because a chain of merges (A into B, then B into C) can end differently if the merges reach Braze out of order.
How the user endpoint is chosen. /users/track and /users/track/bulk have separate rate limits, so large syncs use both at once. Each time a request can go out, it sends the next 1,000 objects to bulk if bulk has capacity right now, and the next 75 to /users/track if not. Bulk fills up to its limit and /users/track carries the rest. At 80% of Braze’s standard limits that allows up to 100,000 objects a second, against 60,000 for /users/track alone. Braze typically answers /users/track in well under 100 ms, so these rates are reachable with the up to 128 requests a sync keeps in flight. In practice, reading from your warehouse is often the slower side. Syncs with fewer than 1,000 objects in a batch, typically incremental ones, use /users/track only: Braze serves it first, and a bulk request would be mostly empty.
Not every account has bulk: Braze documents it as a limited beta, the API key needs the users.track.bulk permission, and an account’s bulk limit may be below 1,000 objects. If Braze refuses a bulk request, those objects are resent to /users/track, the sync uses /users/track alone for the rest of the run, and the run log says so. No rows are lost, and nothing is applied twice, because Braze processes nothing in a request it refuses.
Choose /users/track only if Braze has asked you not to use the bulk endpoint, which it gives lower priority at peak times. Braze Cloud Data Ingestion counts against the same limits, so running it alongside a sync gives no extra room.
Braze limits depend on your contract, and /users/track also has an hourly limit on top of the 3-second one. Syncs follow the rate-limit headers Braze returns and pause when a limit is used up, so a lower hourly limit slows a sync down rather than failing it. If other systems use the same Braze workspace heavily, set Max requests per second.
Pacing is shared by everything sending to the destination. Syncs, audience syncs, journey sends and realtime syncs to the same Braze destination draw from one budget per endpoint. Running two at once splits the rate between them rather than doubling it, and when the headers show the window filling, all of them slow down together. When Braze says a limit is used up, all of them pause, but only on the endpoint that is used up. If you have set a request rate limit on the destination, it applies on top, to all endpoints together.
Order of updates to one user. Requests go out in parallel, so if one batch holds two attribute updates for the same user (a model whose primary key is not unique), either may land last. Braze also serves /users/track ahead of bulk at peak times. Events and purchases are unaffected, because each carries its own time.
Realtime syncs
A Braze destination can also receive a realtime sync from a realtime audience: one person at a time, within seconds of the event that changed their answer, rather than a list on a schedule. The same destination — REST endpoint and API key — serves both.
Because Braze segments are filters rather than lists, a realtime sync records membership the same way a scheduled audience sync does: the audience is added to the membership array (audiences by default) when the person joins and removed when they leave, never deleting the profile. Optionally it also sends a custom event each time. Use the same membership attribute and value on both kinds of sync and one segment covers both. The person is matched by external_id, which is the audience’s destination key. Settings and the full behaviour are under Realtime Syncs → Braze.
Troubleshooting
Authentication failed: invalid API key
Verify your REST API key in Braze Settings > API Keys. Ensure the key has the required permissions for the selected object type.
Incorrect REST endpoint
Each Braze cluster has a different REST endpoint. Select the endpoint that matches your Braze dashboard URL. For example, if your dashboard is at dashboard-01.braze.com, use US-01.
The dropdown is a suggestion list, not a closed set — Braze provisions new clusters from time to time. If yours is missing, pick Enter a custom value and paste the REST endpoint exactly as it appears on the APIs and Identifiers page. It must be a base URL with a scheme and no path (https://rest.iad-07.braze.com, not rest.iad-07.braze.com or https://rest.iad-07.braze.com/users/track).
Array of objects: duplicate or leftover objects
Duplicates come from a first sync into an attribute that already held objects, a run that was repeated after it stopped part-way, or objects another system added to the same attribute. Leftover objects after an object moved between users mean the sync’s primary key does not include the user. Key the sync on a column that combines the user and the object identifier.
Clearing the attribute in Braze does not make an existing sync fill it again: each run sends only the rows that changed, and an update cannot re-create an object that is gone. To rebuild the arrays, pause the sync, clear the attribute in Braze, and create a new sync with the same settings. Its first run sends every row as new. Do not clear an attribute that another system also writes to, because the sync will not restore that system’s objects.
Array of objects: rows fail after a Braze server error
A request that adds objects is not retried after a 5xx or a timeout, because Braze may already have applied it. Its rows are reported failed. A row that failed this way is sent again only when it next changes.
External ID not found
Braze requires an external_id for most operations. Ensure your model includes a column that maps to the user’s external ID in Braze.
Rate limiting
Braze enforces rate limits on its API endpoints. Syncs stay under them (see Throughput) and wait out any 429 for as long as Braze asks. If a sync’s requests fail with 429 after retries, another system is using most of the same Braze limit; set Max requests per second lower. A run log warning that /users/track/bulk was refused means the API key lacks users.track.bulk. The sync still delivers everything through /users/track, only more slowly.