# Braze

Source: https://gokarla.io/docs/guides/notify/integrations/braze

# Braze

:::info

The Braze integration allows Karla to send delivery and claims events as [custom events](https://www.braze.com/docs/user_guide/data/activation/custom_data/custom_events) to your Braze account, so you can build [Canvas](https://www.braze.com/docs/user_guide/engagement_tools/canvas) workflows for transactional emails.

:::

## What we need from you

To connect Karla to your Braze account, we need two things:

1. A **REST API Key** with the `users.track` permission
2. Your **Braze REST Endpoint URL** (e.g., `https://rest.fra-01.braze.eu`)

Follow the steps below to create these in your Braze dashboard.

## Setup

### 1. Open Braze Settings

Navigate to your Braze dashboard, click the **Settings** icon in the top navigation bar, and select [APIs and Identifiers](https://www.braze.com/docs/user_guide/administrative/app_settings/api_settings_tab) from the sidebar.

### 2. Create a REST API Key

In the **REST API Keys** section, click `Create New API Key`. Name it **Karla Integration** for easy identification.

### 3. Assign the required permission

Select the **`users.track`** permission. This is the only permission Karla needs. It allows us to send custom events to your Braze instance via the [`/users/track`](https://www.braze.com/docs/api/endpoints/user_data/post_user_track/) endpoint.

### 4. Save and copy

Click `Save`. **Copy the API key immediately** — it cannot be viewed again after you navigate away.

:::warning

Once created, a REST API key's permissions cannot be edited. If you need to change permissions, create a new key and replace the old one.

:::

### 5. Find your REST Endpoint URL

On the same **APIs and Identifiers** page, locate your **REST Endpoint URL**. It will look like `https://rest.fra-01.braze.eu` or `https://rest.iad-03.braze.com`, depending on your [Braze instance](https://www.braze.com/docs/api/basics/#endpoints).

### 6. Configure in Karla

In the [Karla portal](https://portal.gokarla.io/), go to `Settings` > `Integrations` > `Braze`.

![braze 1](/docs/content/docs/notify/integrations/assets/braze-1.png)

1. Paste your **REST API Key**
2. Enter your **REST Endpoint URL**
3. Click **Save**

## How it works

Once connected, Karla sends [custom events](https://www.braze.com/docs/user_guide/data/activation/custom_data/custom_events) to Braze every time a shipment or claim status changes. All events are prefixed with `karla_` (e.g., `karla_shipment_delivered`).

You can then create [Canvas](https://www.braze.com/docs/user_guide/engagement_tools/canvas) workflows that trigger on these events to send transactional emails to your customers.

### Recommended event groups to start with

These 7 event groups cover the most important delivery scenarios:

| Event group                                  | When it fires                                                  |
| -------------------------------------------- | -------------------------------------------------------------- |
| `karla_shipment_in_transit`                  | Shipment is on its way                                         |
| `karla_shipment_out_for_delivery`            | Shipment is out for delivery                                   |
| `karla_shipment_delivered_all_events`        | Any delivery event (delivered, to neighbor, parcel shop, etc.) |
| `karla_shipment_carrier_delay`               | Carrier reports a delay                                        |
| `karla_shipment_damaged`                     | Shipment is damaged                                            |
| `karla_shipment_not_picked_up_then_returned` | Customer didn't pick up, returned to sender                    |
| `karla_shipment_failed_returned`             | Delivery failed, returned to sender                            |

For the full list of event groups and their properties, see the [Events Reference](/docs/platform/events/overview).

## Creating a Canvas workflow

1. Go to `Messaging` > `Canvas` and click **Create Canvas**
2. Set the entry type to **Action-Based** and the trigger to **Perform Custom Event**
3. Select the Karla event you want (e.g., `karla_shipment_delivered`)
4. Build your message using event properties with Liquid syntax:

```liquid
{{canvas_entry_properties.${order_number}}}
{{canvas_entry_properties.${tracking_number}}}
{{canvas_entry_properties.${carrier_reference}}}
{{canvas_entry_properties.${expected_delivery_date}}}
```

For detailed Canvas setup instructions, see the [Braze Canvas documentation](https://www.braze.com/docs/user_guide/engagement_tools/canvas).

## Inserting the tracking page link

Use Liquid personalization to include a tracking page link in your emails. Replace `slug` with your Karla shop identifier:

```liquid title="Karla hosted tracking page"
https://app.gokarla.io/track/slug?orderNumber={{canvas_entry_properties.${order_number}}}&zipCode={{canvas_entry_properties.${zip_code}}}&ref=karla
```

```liquid title="Embedded tracking page"
https://yourshop.com/pages/tracking?orderNumber={{canvas_entry_properties.${order_number}}}&zipCode={{canvas_entry_properties.${zip_code}}}&ref=karla
```

## Going live

:::warning

Make sure you have disabled any [frequency caps](https://www.braze.com/docs/user_guide/engagement_tools/campaigns/building_campaigns/rate-limiting/#frequency-capping) for transactional emails so that all customers receive their shipping updates.

:::

## Support

- **Karla Integration Support**: [support@gokarla.io]
- **Braze Documentation**: [Braze Canvas Guide](https://www.braze.com/docs/user_guide/engagement_tools/canvas)