Skip to main content

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: 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.activated

Sent on every account activation: first links, reconnects, and routine sign-ins. Example connection.activated event

connection.unauthenticated

Sent when a connection moves from active to unauthenticated because the customer must sign in again, for example after a retailer password change. Example connection.unauthenticated event

connection.disconnected

Sent when the consumer, your app through the API, or an assistant through the disconnect_connection tool in Subtotal: For Brands disconnects the connection. Example connection.disconnected event

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.
Unlike the other connection.* events, the profile payload is flat: its fields sit directly under payload, not under payload.connection.
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).
Example connection.profile.created event

connection.profile.updated

Sent 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. Example connection.profile.updated event

purchase.created

The 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. status is the purchase status when the event is sent. A later status change sends no event; read it from GET /purchases/. 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.

Purchase status

status is the purchase status the retailer last showed. The value is a string, or null when unknown. The possible string values are:
  • pending
  • shipped
  • ready_for_pickup
  • completed
  • cancelled
Status is collected for Amazon, Walmart, and Target. Some purchases from these retailers, and purchases collected before October 2026, have null. completed and cancelled are final. Once a purchase reaches either status, its status does not change again. Example purchase.created event