> ## Documentation Index
> Fetch the complete documentation index at: https://docs.masivo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Braze integration

> Sync Masivo customers, events, purchases and audiences to Braze

## What you can sync

* Customers: create, update, and delete users in Braze
* Events: send behavioral events as Braze custom events
* Purchases: send order line items as Braze purchases
* Audiences: add a custom attribute with the Masivo audience name

## Prerequisites

* A Braze REST API Key with permissions to create users, track events, and
  purchases

<Info>Your Masivo customer `id` will be used as Braze `external_id`</Info>

## Rate limits and batching

Braze has specific limits that Masivo respects automatically:

* **Rate limit**: 3,000 calls every 3 seconds
* **Batch size**: Each call can include up to 75 attributes, 75 events, and 75 purchases
* **User deletion limit**: 50 user deletions per request (Braze API limitation)
* Masivo groups messages by account and sends them in optimal batches to stay within these limits

## Configuration

1. Go to Settings → Integrations → Braze in the Masivo dashboard.
2. Paste your Braze API Key.
3. **Configure your Braze REST Endpoint**: Each Braze account has a unique REST Endpoint (e.g., `https://rest.iad-01.braze.com` for US East, `https://rest.fra-01.braze.com` for EU).
4. Enable the toggles you need:
   * Audiences
   * Events
   * Purchases (only fulfilled purchases are synced)
   * Customer tags
   * Customers: Create, Update, Delete

<Warning>
  Make sure to use the correct Braze REST Endpoint for your account. Using the
  wrong REST Endpoint will cause API calls to fail. You can find your account's
  REST Endpoint in the Braze dashboard under **Settings → API Settings**.{" "}
</Warning>

## How it works

Once configured, Masivo automatically syncs your data to Braze:

1. **Real-time sync**: Data is sent to Braze as soon as events occur in Masivo
2. **Smart validation**: Masivo checks your configuration and only sends data that meets your criteria
3. **Efficient processing**: Data is batched and sent in optimal groups to respect Braze's limits
4. **Error handling**: Failed syncs are logged and don't affect other integrations

### What gets validated

Before sending data to Braze, Masivo validates:

* Your API configuration is correct
* The specific features you want to sync are enabled
* Data meets your business rules (e.g., only fulfilled purchases)
* Events are not internal system events

## How purchases work in Braze

**Purchases are additive, not replacement-based:**

* If the user already exists in Braze, the `purchases` block **adds the purchase to their history** (doesn't delete previous ones)
* If the user doesn't exist, Braze creates the user and then registers the purchase
* Each purchase has its own identifier and timestamp, maintaining a complete transaction history
* **Reversals and cancellations** are handled by sending additional purchases with negative prices

This approach allows Braze to calculate accurate Lifetime Revenue by summing all purchases (including negative ones) while preserving the complete purchase history.

## Event properties behavior

When sending events with custom properties:

* **Flat key-value properties are supported** but won't automatically appear in the user profile UI
* **Only flat properties** (not nested objects) are properly visible and segmentable
* Masivo flattens complex event data before sending to ensure compatibility

<Warning>
  Protected internal events such as REGISTRATION, FULFILL, REVERSE, EXPIRE,
  CANCEL, REDEEM\_COUPON and TIER\_ADJUSTMENT are not forwarded to Braze.
</Warning>

## Audience synchronization

### Audience calculation operations

* Sends audience information as custom attributes to Braze
* Requires `audience_id` in your data
* **Automatic prefix**: Masivo adds a "masivo\_" prefix to audience names to prevent conflicts with existing Braze audiences

### Audience DELETE operations

* Automatically gathers all customers in the audience before deletion
* Sends complete customer list to Braze for proper cleanup
* Ensures Braze has all necessary information for audience removal

<Note>
  When deleting audiences, Masivo automatically collects all customer data to
  ensure Braze can properly clean up the audience information.
</Note>

<Info>
  Masivo automatically prefixes audience names with "masivo\_" to avoid naming
  conflicts with existing Braze audiences. For example, an audience named "VIP
  Customers" in Masivo will appear as "masivo\_VIP Customers" in Braze.
</Info>