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

# Event types

> Subtotal custom events and payloads delivered to Braze.

Subtotal delivers the following custom events to Braze via the [`users.track`](https://www.braze.com/docs/api/endpoints/user_data/post_user_track/) endpoint. Each event can be used to trigger campaigns, build segments, or power Canvas journeys.

## subtotal\_purchase

Triggered when a purchase is detected for a connected account. Sent for each historical purchase and for any newly detected purchases.

| Key           | Type   | Description                                             |
| :------------ | :----- | :------------------------------------------------------ |
| `purchase_id` | string | Identifier for the purchase                             |
| `total`       | string | The grand total paid by the customer                    |
| `tax`         | string | The sales tax that was paid                             |
| `subtotal`    | string | The subtotal of the purchase                            |
| `item_count`  | number | The number of items in the purchase                     |
| `retailer`    | string | Identifier for the retailer where the purchase was made |
| `upcs`        | array  | The UPCs associated with each item in the purchase      |
| `brands`      | array  | The brands associated with each item in the purchase    |
| `source`      | string | Always `"subtotal"`                                     |

**Example**

```json theme={null}
{
  "purchase_id": "01KEVN1ZPM9H19JSHGN5NF0M69",
  "total": "44.64",
  "tax": "1.60",
  "subtotal": "43.04",
  "item_count": 15,
  "retailer": "walmart",
  "upcs": ["040000476528", "016000124790", "041331027878", "013000001243", "049000031171"],
  "brands": ["frenchs", "heinz", "spam", "jif", "cheerios"],
  "source": "subtotal"
}
```

## subtotal\_account\_connected

Triggered when a consumer links a retail account.

| Key             | Type   | Description                   |
| :-------------- | :----- | :---------------------------- |
| `connection_id` | string | Identifier for the connection |
| `retailer`      | string | Identifier for the retailer   |
| `source`        | string | Always `"subtotal"`           |

**Example**

```json theme={null}
{
  "connection_id": "01KFRSK9J11G807TAY0GCYSW67",
  "retailer": "walmart",
  "source": "subtotal"
}
```

## subtotal\_account\_disconnected

Triggered when a consumer disconnects a retail account.

| Key             | Type   | Description                                                                             |
| :-------------- | :----- | :-------------------------------------------------------------------------------------- |
| `connection_id` | string | Identifier for the connection                                                           |
| `retailer`      | string | Identifier for the retailer                                                             |
| `link_url`      | string | The [Link URL](/docs/subtotal-link/link-urls) that can be used to reconnect the account |
| `source`        | string | Always `"subtotal"`                                                                     |

**Example**

```json theme={null}
{
  "connection_id": "01KFRSK9J11G807TAY0GCYSW67",
  "retailer": "walmart",
  "link_url": "https://link.subtotal.com/zSG5nWHy?connection_id=01KFRSK9J11G807TAY0GCYSW67",
  "source": "subtotal"
}
```

## subtotal\_connection\_unauthenticated

Triggered when an active connection becomes unauthenticated and requires the customer to reauthenticate (e.g. after a retailer password change).

| Key             | Type   | Description                                                                             |
| :-------------- | :----- | :-------------------------------------------------------------------------------------- |
| `connection_id` | string | Identifier for the connection                                                           |
| `retailer`      | string | Identifier for the retailer                                                             |
| `link_url`      | string | The [Link URL](/docs/subtotal-link/link-urls) that can be used to reconnect the account |
| `source`        | string | Always `"subtotal"`                                                                     |

**Example**

```json theme={null}
{
  "connection_id": "01KFRSK9J11G807TAY0GCYSW67",
  "retailer": "walmart",
  "link_url": "https://link.subtotal.com/zSG5nWHy?connection_id=01KFRSK9J11G807TAY0GCYSW67",
  "source": "subtotal"
}
```

## subtotal\_connection\_reauthenticated

Triggered when a consumer re-authenticates a previously unauthenticated connection.

| Key             | Type   | Description                   |
| :-------------- | :----- | :---------------------------- |
| `connection_id` | string | Identifier for the connection |
| `retailer`      | string | Identifier for the retailer   |
| `source`        | string | Always `"subtotal"`           |

**Example**

```json theme={null}
{
  "connection_id": "01KFRSK9J11G807TAY0GCYSW67",
  "retailer": "walmart",
  "source": "subtotal"
}
```

## Profile Created

Triggered the first time Subtotal captures a consumer's profile for a connection — their identity details and purchase metrics scoped to your brands. Use it to enrich Braze user profiles with first-party retail identity.

| Key                        | Type   | Description                                                                    |
| :------------------------- | :----- | :----------------------------------------------------------------------------- |
| `connection_id`            | string | Identifier for the connection                                                  |
| `first_name`               | string | Consumer's first name (`null` if unavailable)                                  |
| `last_name`                | string | Consumer's last name (`null` if unavailable)                                   |
| `email`                    | string | Consumer's email address (`null` if unavailable)                               |
| `mobile`                   | string | Consumer's mobile phone number (`null` if unavailable)                         |
| `postal_code`              | string | Consumer's postal code (`null` if unavailable)                                 |
| `account_created_date`     | string | When the consumer's retailer account was created (ISO 8601; `null` if unknown) |
| `total_purchases`          | number | All-time number of purchases on the connected account                          |
| `last_purchase_date`       | string | Date of the most recent purchase (ISO 8601; `null` if none)                    |
| `brand_purchases`          | number | Number of those purchases matching your brands                                 |
| `last_brand_purchase_date` | string | Date of the most recent brand purchase (ISO 8601; `null` if none)              |
| `brand_purchase_rate`      | number | `brand_purchases` ÷ `total_purchases`, from `0.0` to `1.0`                     |
| `source`                   | string | Always `"subtotal"`                                                            |

**Example**

```json theme={null}
{
  "connection_id": "01KFRSK9J11G807TAY0GCYSW67",
  "first_name": "Jessica",
  "last_name": "Smith",
  "email": "jessica@acme.com",
  "mobile": "+123456789",
  "postal_code": "84101",
  "account_created_date": "2024-03-12T00:00:00Z",
  "total_purchases": 42,
  "last_purchase_date": "2026-01-15T14:30:00Z",
  "brand_purchases": 7,
  "last_brand_purchase_date": "2026-01-14T09:45:00Z",
  "brand_purchase_rate": 0.17,
  "source": "subtotal"
}
```

## Profile Updated

Triggered when a previously captured profile changes — for example an updated email or postal code, or when new purchases shift the brand-purchase metrics. Carries the same properties as **Profile Created**.

| Key                        | Type   | Description                                                                    |
| :------------------------- | :----- | :----------------------------------------------------------------------------- |
| `connection_id`            | string | Identifier for the connection                                                  |
| `first_name`               | string | Consumer's first name (`null` if unavailable)                                  |
| `last_name`                | string | Consumer's last name (`null` if unavailable)                                   |
| `email`                    | string | Consumer's email address (`null` if unavailable)                               |
| `mobile`                   | string | Consumer's mobile phone number (`null` if unavailable)                         |
| `postal_code`              | string | Consumer's postal code (`null` if unavailable)                                 |
| `account_created_date`     | string | When the consumer's retailer account was created (ISO 8601; `null` if unknown) |
| `total_purchases`          | number | All-time number of purchases on the connected account                          |
| `last_purchase_date`       | string | Date of the most recent purchase (ISO 8601; `null` if none)                    |
| `brand_purchases`          | number | Number of those purchases matching your brands                                 |
| `last_brand_purchase_date` | string | Date of the most recent brand purchase (ISO 8601; `null` if none)              |
| `brand_purchase_rate`      | number | `brand_purchases` ÷ `total_purchases`, from `0.0` to `1.0`                     |
| `source`                   | string | Always `"subtotal"`                                                            |

**Example**

```json theme={null}
{
  "connection_id": "01KFRSK9J11G807TAY0GCYSW67",
  "first_name": "Jessica",
  "last_name": "Smith",
  "email": "jessica.smith@acme.com",
  "mobile": "+123456789",
  "postal_code": "84101",
  "account_created_date": "2024-03-12T00:00:00Z",
  "total_purchases": 43,
  "last_purchase_date": "2026-02-02T18:05:00Z",
  "brand_purchases": 8,
  "last_brand_purchase_date": "2026-02-02T18:05:00Z",
  "brand_purchase_rate": 0.19,
  "source": "subtotal"
}
```