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

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

\<table><thead><tr><th scope="col">Trigger</th>
          \<th scope="col">Webhook event type</th>
          \<th scope="col">Sent when</th></tr></thead>
      \<tbody><tr><td>[Purchase shared](#purchase-created)</td>
            \<td>`purchase.created`</td>
            \<td>A purchase is shared with your brand: a new purchase from a linked
account, or the history shared when an account connects or
reconnects.</td></tr>
        \<tr><td>[Account connected / Account reconnected](#connection-activated)</td>
            \<td>`connection.activated`</td>
            \<td>Sent on every account activation: first links, reconnects, and routine sign-ins.</td></tr>
        
        \<tr><td>[Account needs reconnecting](#connection-unauthenticated)</td>
            \<td>`connection.unauthenticated`</td>
            \<td>A connection loses access at the retailer.</td></tr>
        \<tr><td>[Account disconnected](#connection-disconnected)</td>
            \<td>`connection.disconnected`</td>
            \<td>The consumer, or your app through the API, disconnects the
connection.</td></tr>
        \<tr><td>[Profile shared](#connection-profile-created)</td>
            \<td>`connection.profile.created`</td>
            \<td>Subtotal first collects a retail account's profile, and it
goes once to each connection linked to that account at that
moment, not to a connection made later.</td></tr>
        \<tr><td>[Profile updated](#connection-profile-updated)</td>
            \<td>`connection.profile.updated`</td>
            \<td>A collected profile changes.</td></tr></tbody></table>

## Properties included with every eventThese properties are included with each webhook request:| Key | Type | Description |
| :- | :- | :- |
| type | string | The webhook event type |
| id | string | Identifier for one delivery, reused on retries and redeliveries. See [Delivery and retries](https://docs.subtotal.com/docs/webhooks/delivery-and-retries.md#idempotency). |
| is\_simulated | boolean | Present and `true` only when the event comes from the [Event Simulator](https://docs.subtotal.com/docs/event-simulator.md); real events omit it, so treat a missing value as `false`. Only destinations that accept simulated events receive simulated events. |
| payload | object | The event data. Its shape depends on `type`. |The same purchase can arrive in more than one `purchase.created` event: once for each active connection on the retail account. It can arrive again each time a connection that lost access signs in. Deduplicate purchases on `payload.purchase.purchase_id` with `payload.connection.connection_id`.Below are all supported event types and their corresponding payload structures.## connection.activatedSent on every account activation: first links, reconnects, and routine sign-ins.| 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.unauthenticatedSent when a connection moves from `active` to `unauthenticated` because the customer must sign in again, for example after a retailer password change.| 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.disconnectedSent when the consumer, your app through the API, or an assistant through the [`disconnect_connection`](https://docs.subtotal.com/docs/connector/tools#disconnect_connection) tool in Subtotal: For Business disconnects the connection.| 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.createdSent 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]
>
> Profile events are only delivered for **active** connections. While a connection is `unauthenticated` or `disconnected` you will not receive profile events for it; if the profile changed in the meantime, the connection receives a single catch-up event when it is re-linked (alongside `connection.activated`).| 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.updatedSent when the collected identity changes: name, email, mobile, postal code or retailer account creation date. New purchases alone do not send it. Each profile event carries the latest purchase metrics.The payload has the same shape as `connection.profile.created`. This event is only delivered while the connection is active. Changes collected while a connection is `unauthenticated` or `disconnected` arrive as one event when the connection signs in again.| 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.createdThe `purchase.created` event is sent when a purchase from a customer's connected retailer account is shared with your brand. This may differ from when Subtotal first collected the purchase.The dashboard calls this trigger [**Purchase shared**](https://docs.subtotal.com/docs/concepts.md#purchase-triggers).`status` is the purchase status when the event is sent. A later status change sends no event; read it from [GET /purchases/{purchase_id}](https://docs.subtotal.com/docs/api-reference/purchases/get-purchase.md).When an account first connects, the destination's `purchase.created` subscription receives the account's history. When a connection signs in after it lost access, the destination's `connection.activated` subscription also sends `purchase.created` for purchases collected since that loss. Subscribe to both to receive every shared purchase.| 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.subtotal | string (decimal) | The subtotal of the purchase, for example `"43.50"` |
| payload.purchase.tax | string (decimal) | The sales tax that was paid, for example `"4.35"` |
| payload.purchase.total | string (decimal) | Total amount of the purchase, for example `"47.85"` |
| payload.purchase.purchase\_type | string | The purchase type: `in_store`, `online`, `delivery`, `pickup`, `return`, or `null` |
| payload.purchase.status | string or null | The purchase status when the event is sent: `pending`, `shipped`, `ready_for_pickup`, `completed`, or `cancelled`. `null` when unknown. |
| payload.purchase.items\[].item\_id | string | Identifier for the item |
| payload.purchase.items\[].price | string (decimal) | Price of the item, for example `"5.99"` |
| payload.purchase.items\[].quantity | string (decimal) | Quantity as shown on the receipt, for example `"2.00"`; items sold by weight show `"1"`. |
| 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 or null | Universal Product Code (UPC); `null` unless the collected product identifier has 14 digits |
| payload.purchase.items\[].product.brand | string | The brand associated with the product |### Purchase status<Snippet file="snippets/purchase-status.mdx" />**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",
      "purchase_type": "in_store",
      "status": "completed",
      "items": [
        {
          "item_id": "01JV7ZDWC9GN1VPR41K3BY08X9",
          "price": "5.99",
          "quantity": "2.00",
          "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.00",
          "product": {
            "product_id": "01J51S0JYV6N7K1030CV1ZKSCA",
            "name": "Trail Mix",
            "description": "Trail Mix Family Size", 
            "upc": "009876543210",
            "brand": "harvest-one"
          }
        },
        {
          "item_id": "01JV7ZDWC9GN1VPR41K3BY08X9",
          "price": "8.50",
          "quantity": "1",
          "product": {
            "product_id": "01J51S0JYV6N7K1030CV1ZKSCA",
            "name": "Organic Cherries",
            "description": "Organic Cherries, sold by the pound",
            "upc": "011122233344",
            "brand": "harvest-one"
          }
        }
      ]
    }
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.