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.

Purchased at Retailer

Triggered when a purchase is shared with your brand. Sent for qualifying historical purchases and newly shared purchases. This is the Braze event name for the Purchase shared trigger. The delivered name remains Purchased at Retailer. 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"
}

Connected an Account

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

Disconnected an Account

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

Unauthenticated Connection

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

Reauthenticated Connection

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

Purchased at Retailer

Connected an Account

Disconnected an Account

Unauthenticated Connection

Reauthenticated Connection

Profile Created

Profile Updated

​Purchased at Retailer

​Connected an Account

​Disconnected an Account

​Unauthenticated Connection

​Reauthenticated Connection

​Profile Created

​Profile Updated

Purchased at Retailer

Connected an Account

Disconnected an Account

Unauthenticated Connection

Reauthenticated Connection

Profile Created

Profile Updated