Event types

Subtotal delivers the following custom events to Braze via the users.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. status is a new field. Other fields did not change, and events are sent at the same time as before. Events carry the purchase status when they are sent. Later status changes are not sent as events. Read the latest status from GET /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
`status`	string or null	The purchase status when the event is sent: `pending`, `shipped`, `ready_for_pickup`, `completed`, or `cancelled`. `null` when unknown.
`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

{
  "purchase_id": "01KEVN1ZPM9H19JSHGN5NF0M69",
  "total": "44.64",
  "tax": "1.60",
  "subtotal": "43.04",
  "item_count": 15,
  "status": "completed",
  "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

{
  "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 that can be used to reconnect the account
`source`	string	Always `"subtotal"`

Example

{
  "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 that can be used to reconnect the account
`source`	string	Always `"subtotal"`

Example

{
  "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

{
  "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

{
  "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

{
  "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"
}

Documentation

Products

Developers

Apps

Guides

subtotal_purchase

subtotal_account_connected

subtotal_account_disconnected

subtotal_connection_unauthenticated

subtotal_connection_reauthenticated

Profile Created

Profile Updated

​subtotal_purchase

​subtotal_account_connected

​subtotal_account_disconnected

​subtotal_connection_unauthenticated

​subtotal_connection_reauthenticated

​Profile Created

​Profile Updated

subtotal_purchase

subtotal_account_connected

subtotal_account_disconnected

subtotal_connection_unauthenticated

subtotal_connection_reauthenticated

Profile Created

Profile Updated