> ## 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 event types and payloads for Klaviyo segments and flows.

Each event can be used to **create segments** or **trigger flows** in Klaviyo.

## Purchased at Retailer

Sent for each historical purchase and for any newly detected purchases.

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

**Example**

```json theme={null}
{
  "purchase_id": "01KEVN1ZPM9H19JSHGN5NF0M69",
  "retailer": "walmart",
  "date": "2025-05-31T14:48:23Z",
  "item_count": 15,
  "subtotal": 43.04,
  "tax": 1.6,
  "total": 44.64,
  "brands": ["frenchs", "heinz", "spam", "jif", "yogi-tea", "cheerios", "m&ms", "goya", "coca-cola"],
  "upcs": ["040000476528", "016000124790", "041331027878", "041331027878", "041331027878", "041331027878", "013000001243", "049000031171", "049000040869", "049000040869", "076950450363", "037600138727", "049000067231", "041500007007", "051500255162"]
}
```

## Connected an Account

Sent when a customer connects a retailer account.

| Key             | Type   | Description                   |
| --------------- | ------ | ----------------------------- |
| `connection_id` | string | Identifier for the connection |
| `retailer`      | string | Identifier for the retailer   |

**Example**

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

## Disconnected an Account

Sent when a customer disconnects a retailer 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 |

**Example**

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

## Reauthenticated Connection

Sent when an unauthenticated connection becomes reauthenticated.

| Key             | Type   | Description                   |
| --------------- | ------ | ----------------------------- |
| `connection_id` | string | Identifier for the connection |
| `retailer`      | string | Identifier for the retailer   |

**Example**

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

## Unauthenticated Connection

Sent 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 | Unique 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 |

**Example**

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

## Profile Created

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

| Key                        | Type   | Description                                                                    |
| -------------------------- | ------ | ------------------------------------------------------------------------------ |
| `connection_id`            | string | Identifier for the connection                                                  |
| `first_name`               | string | Customer's first name (`null` if unavailable)                                  |
| `last_name`                | string | Customer's last name (`null` if unavailable)                                   |
| `email`                    | string | Customer's email address (`null` if unavailable)                               |
| `mobile`                   | string | Customer's mobile phone number (`null` if unavailable)                         |
| `postal_code`              | string | Customer's postal code (`null` if unavailable)                                 |
| `account_created_date`     | string | When the customer'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`                     |

**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
}
```

## Profile Updated

Sent 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 | Customer's first name (`null` if unavailable)                                  |
| `last_name`                | string | Customer's last name (`null` if unavailable)                                   |
| `email`                    | string | Customer's email address (`null` if unavailable)                               |
| `mobile`                   | string | Customer's mobile phone number (`null` if unavailable)                         |
| `postal_code`              | string | Customer's postal code (`null` if unavailable)                                 |
| `account_created_date`     | string | When the customer'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`                     |

**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
}
```