> ## 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

> Subscribe to system events to receive real-time notifications.

## Overview

Webhooks let you subscribe to Subtotal system events and receive real-time HTTP requests when those events occur. Use webhooks to keep your systems in sync with connection and purchase activity.

## Properties included with every event

These properties are included with each webhook request:

| Key     | Type   | Description                |
| :------ | :----- | :------------------------- |
| type    | string | The webhook event type     |
| id      | string | Identifier for the webhook |
| payload | string | The payload of the webhook |

Below are all supported event types and their corresponding payload structures.

## connection.activated

Connections are `activated` when a customer successfully links their account.

| Key                               | Type   | Description                                    |
| :-------------------------------- | :----- | :--------------------------------------------- |
| payload.connection.connection\_id | string | Identifier for the connection                  |
| payload.connection.customer\_id   | string | Identifier for the associated customer         |
| payload.connection.retailer\_id   | string | Identifier for the retailer in the connection  |
| payload.connection.email          | string | Email address of the associated customer       |
| payload.connection.mobile         | string | Mobile phone number of the associated customer |
| payload.connection.status         | string | Current status of the connection               |

**Example `connection.activated` event**

```json theme={null}
{
  "type": "connection.activated",
  "id": "01KFJSR44CPH867805V8GJ9VCY",
  "payload": {
    "connection": {
      "connection_id": "01K8BPF23CCZ2FK50STB8EGWAV",
      "customer_id": "01K8BPF2393S9VB6JQT99GK447",
      "retailer_id": "target",
      "email": null,
      "mobile": null,
      "status": "active"
    }
  }
}
```

***

## connection.unauthenticated

Connections move from `activated` to `unauthenticated` when a customer needs to re-authenticate their account. For example, when a customer changes their password with the retailer.

| Key                               | Type   | Description                                    |
| :-------------------------------- | :----- | :--------------------------------------------- |
| payload.connection.connection\_id | string | Identifier for the connection                  |
| payload.connection.customer\_id   | string | Identifier for the associated customer         |
| payload.connection.retailer\_id   | string | Identifier for the retailer in the connection  |
| payload.connection.email          | string | Email address of the associated customer       |
| payload.connection.mobile         | string | Mobile phone number of the associated customer |
| payload.connection.status         | string | Current status of the connection               |

**Example `connection.unauthenticated` event**

```json theme={null}
{
  "type": "connection.unauthenticated",
  "id": "01KFJSR44CPH867805V8GJ9VCY",
  "payload": {
    "connection": {
      "connection_id": "01K8BPF23CCZ2FK50STB8EGWAV",
      "customer_id": "01K8BPF2393S9VB6JQT99GK447",
      "retailer_id": "target",
      "email": null,
      "mobile": null,
      "status": "unauthenticated"
    }
  }
}
```

***

## connection.disconnected

Connections move to `disconnected` status when a customer disconnects their account.

| Key                               | Type   | Description                                    |
| :-------------------------------- | :----- | :--------------------------------------------- |
| payload.connection.connection\_id | string | Identifier for the connection                  |
| payload.connection.customer\_id   | string | Identifier for the associated customer         |
| payload.connection.retailer\_id   | string | Identifier for the retailer in the connection  |
| payload.connection.email          | string | Email address of the associated customer       |
| payload.connection.mobile         | string | Mobile phone number of the associated customer |
| payload.connection.status         | string | Current status of the connection               |

**Example `connection.disconnected` event**

```json theme={null}
{
  "type": "connection.disconnected",
  "id": "01KFJSR44CPH867805V8GJ9VCY",
  "payload": {
    "connection": {
      "connection_id": "01K8BPF23CCZ2FK50STB8EGWAV",
      "customer_id": "01K8BPF2393S9VB6JQT99GK447",
      "retailer_id": "target",
      "email": null,
      "mobile": null,
      "status": "disconnected"
    }
  }
}
```

***

## connection.profile.created

Sent the first time Subtotal captures a consumer's profile for a connection — their identity details from the linked retailer account, together with purchase metrics scoped to your brands.

<Note>
  Unlike the other `connection.*` events, the profile payload is **flat**: its fields sit directly under `payload`, not under `payload.connection`.
</Note>

| Key                                 | Type   | Description                                                                    |
| :---------------------------------- | :----- | :----------------------------------------------------------------------------- |
| payload.connection\_id              | string | Identifier for the connection                                                  |
| payload.first\_name                 | string | Consumer's first name (`null` if unavailable)                                  |
| payload.last\_name                  | string | Consumer's last name (`null` if unavailable)                                   |
| payload.email                       | string | Consumer's email address (`null` if unavailable)                               |
| payload.mobile                      | string | Consumer's mobile phone number (`null` if unavailable)                         |
| payload.postal\_code                | string | Consumer's postal code (`null` if unavailable)                                 |
| payload.account\_created\_date      | string | When the consumer's retailer account was created (ISO 8601; `null` if unknown) |
| payload.total\_purchases            | number | All-time number of purchases on the connected account                          |
| payload.last\_purchase\_date        | string | Date of the most recent purchase (ISO 8601; `null` if none)                    |
| payload.brand\_purchases            | number | Number of those purchases you are authorized to see (matching your brands)     |
| payload.last\_brand\_purchase\_date | string | Date of the most recent brand purchase (ISO 8601; `null` if none)              |
| payload.brand\_purchase\_rate       | number | `brand_purchases` ÷ `total_purchases`, from `0.0` to `1.0`                     |

**Example `connection.profile.created` event**

```json theme={null}
{
  "type": "connection.profile.created",
  "id": "01KFJSR44CPH867805V8GJ9VCY",
  "payload": {
    "connection_id": "01K8BPF23CCZ2FK50STB8EGWAV",
    "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
  }
}
```

***

## connection.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. The payload is identical in shape to `connection.profile.created`.

| Key                                 | Type   | Description                                                                    |
| :---------------------------------- | :----- | :----------------------------------------------------------------------------- |
| payload.connection\_id              | string | Identifier for the connection                                                  |
| payload.first\_name                 | string | Consumer's first name (`null` if unavailable)                                  |
| payload.last\_name                  | string | Consumer's last name (`null` if unavailable)                                   |
| payload.email                       | string | Consumer's email address (`null` if unavailable)                               |
| payload.mobile                      | string | Consumer's mobile phone number (`null` if unavailable)                         |
| payload.postal\_code                | string | Consumer's postal code (`null` if unavailable)                                 |
| payload.account\_created\_date      | string | When the consumer's retailer account was created (ISO 8601; `null` if unknown) |
| payload.total\_purchases            | number | All-time number of purchases on the connected account                          |
| payload.last\_purchase\_date        | string | Date of the most recent purchase (ISO 8601; `null` if none)                    |
| payload.brand\_purchases            | number | Number of those purchases you are authorized to see (matching your brands)     |
| payload.last\_brand\_purchase\_date | string | Date of the most recent brand purchase (ISO 8601; `null` if none)              |
| payload.brand\_purchase\_rate       | number | `brand_purchases` ÷ `total_purchases`, from `0.0` to `1.0`                     |

**Example `connection.profile.updated` event**

```json theme={null}
{
  "type": "connection.profile.updated",
  "id": "01KFJSR44CPH867805V8GJ9VCY",
  "payload": {
    "connection_id": "01K8BPF23CCZ2FK50STB8EGWAV",
    "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
  }
}
```

***

## purchase.created

The `purchase.created` event is sent when a new purchase is received from a customer's connected retailer account.

We recommend using this event when you need to process customer purchases for your use case.

| Key                                           | Type   | Description                                    |
| :-------------------------------------------- | :----- | :--------------------------------------------- |
| payload.connection.connection\_id             | string | Identifier for the connection                  |
| payload.connection.customer\_id               | string | Identifier for the associated customer         |
| payload.connection.retailer\_id               | string | Identifier for retailer in the connection      |
| payload.connection.email                      | string | Email address of the associated customer       |
| payload.connection.mobile                     | string | Mobile phone number of the associated customer |
| payload.connection.status                     | string | Current status of the connection               |
| payload.purchase.purchase\_id                 | string | Identifier for the purchase                    |
| payload.purchase.date                         | string | Date of the purchase (ISO 8601)                |
| payload.purchase.item\_count                  | number | The number of items in the purchase            |
| payload.purchase.subtotal                     | number | The subtotal of the purchase                   |
| payload.purchase.tax                          | number | The sales tax that was paid                    |
| payload.purchase.total                        | number | Total amount of the purchase                   |
| payload.purchase.items\[].item\_id            | string | Identifier for the item                        |
| payload.purchase.items\[].price               | number | Price of the item                              |
| payload.purchase.items\[].quantity            | number | The quantity purchased                         |
| payload.purchase.items\[].product.product\_id | string | Identifier for the product                     |
| payload.purchase.items\[].product.name        | string | The name of the product                        |
| payload.purchase.items\[].product.description | string | Description of the item                        |
| payload.purchase.items\[].product.upc         | string | Universal identifier for the product (UPC)     |
| payload.purchase.items\[].product.brand       | string | The brand associated with the product          |

**Example `purchase.created` event**

```json theme={null}
{
  "id": "01J51S0JYV6N7K1030CV1ZBDOW",
  "type": "purchase.created",
  "payload": {
    "connection": {
      "connection_id": "01J51S0JYV6N7K1030CV1ZKSCA",
      "customer_id": "01K8HDK6Y9FXM7ES4NJSHZDEKF",
      "retailer_id": "walmart",
      "email": "jessica@acme.com",
      "mobile": "+123456789",
      "status": "active"
    },
    "purchase": {
      "purchase_id": "01J51S0JYV6N7K1030CV1ZKSJH",
      "date": "2025-10-08T14:23:00Z",
      "total": 47.85,
      "subtotal": 43.50,
      "tax": 4.35,
      "items": [
        {
          "item_id": "01JV7ZDWC9GN1VPR41K3BY08X9",
          "price": 5.99,
          "quantity": 2,
          "product": {
            "product_id": "01J51S0JYV6N7K1030CV1ZKSCA", 
            "name": "Sparkling Water 12pk",
            "description": "Sparkling Water 12-Pack - 12 fl oz bottles",
            "upc": "001234567890",
            "brand": "la-croix"
          }
        },
        {
          "item_id": "01K3KS9Q4522E3HG444E4XH1R0",
          "price": 12.99,
          "quantity": 1,
          "product": {
            "product_id": "01J51S0JYV6N7K1030CV1ZKSCA",
            "name": "Trail Mix",
            "description": "Trail Mix Family Size", 
            "upc": "009876543210",
            "brand": "harvest-one"
          }
        },
        {
          "item_id": "01JV7ZDWC9GN1VPR41K3BY08X9",
          "price": 18.53,
          "quantity": 1,
          "product": {
            "product_id": "01J51S0JYV6N7K1030CV1ZKSCA",
            "name": "Face Cream",
            "description": "Moisturizing Face Cream",
            "upc": "011122233344",
            "brand": "glowww"
          }
        }
      ]
    }
  }
}
```