Events — Aggregate

Compute aggregated statistics over events: counts, sums, averages, and min/max — optionally grouped per pass or bucketed over time.

Auth: Bearer token — workspace member (the workspace_id in the body).

---

Aggregate Events

POST /wallethero-api/events/aggregate

Runs one aggregation. With group_by_pass: true the response is an array (one result per pass); otherwise it is a single result object. With group_by_time set, the single result also includes a buckets time series.

Auth: Bearer token — workspace member.

Request Body

Field	Type	Required	Default	Description
workspace_id	string (UUID)	Yes	—	Workspace identifier
function	string	Yes	—	One of count, sum, avg, min, max
field	string	Conditional	—	Field to aggregate for non-count functions. One of amount, points_delta
pass_ids	array<string (UUID)>	No	—	Restrict to specific passes
event_category	string	No	—	One of field_change, transaction, engagement, loyalty, pass_lifecycle
event_types	array<string>	No	—	Restrict to specific event types
field_name	string (≤100)	No	—	Restrict field_change events to a field
time_window	string	No	—	One of day, week, month, quarter, year, all_time
custom_days	number	No	—	Look back N days (1–365); alternative to time_window
from_date	string (ISO 8601)	No	—	Explicit window start
to_date	string (ISO 8601)	No	—	Explicit window end
group_by_pass	boolean	No	false	Return one result per pass
group_by_time	string	No	—	Bucket the single result over time: day, week, or month

Functions

Function	Description	Requires field
count	Count of matching events	No
sum / avg / min / max	Aggregate over amount or points_delta	Yes

Example: Total Revenue This Month

curl -X POST "https://api.wallethero.app/wallethero-api/events/aggregate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "WORKSPACE_ID",
    "function": "sum",
    "field": "amount",
    "event_category": "transaction",
    "event_types": ["purchase"],
    "time_window": "month"
  }'

Response (200) — Single Result

{
  "data": {
    "value": 15420.50,
    "event_category": "transaction",
    "event_types": ["purchase"],
    "time_window": "month",
    "from_date": "2026-05-17T00:00:00.000Z",
    "to_date": "2026-06-16T00:00:00.000Z"
  }
}

Example: Daily Buckets

curl -X POST "https://api.wallethero.app/wallethero-api/events/aggregate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "WORKSPACE_ID",
    "function": "count",
    "event_category": "engagement",
    "event_types": ["check_in"],
    "time_window": "week",
    "group_by_time": "day"
  }'

Response (200) — With Buckets

{
  "data": {
    "value": 342,
    "event_category": "engagement",
    "event_types": ["check_in"],
    "time_window": "week",
    "from_date": "2026-06-09T00:00:00.000Z",
    "to_date": "2026-06-16T00:00:00.000Z",
    "buckets": [
      { "date": "2026-06-09T00:00:00.000Z", "value": 41 },
      { "date": "2026-06-10T00:00:00.000Z", "value": 55 }
    ]
  }
}

Example: Per-Pass Totals

curl -X POST "https://api.wallethero.app/wallethero-api/events/aggregate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "WORKSPACE_ID",
    "function": "sum",
    "field": "amount",
    "event_category": "transaction",
    "time_window": "year",
    "group_by_pass": true
  }'

Response (200) — Per-Pass

{
  "data": [
    { "pass_id": "pass-1", "value": 1250.00 },
    { "pass_id": "pass-2", "value": 890.50 }
  ]
}

SDK

// Single result
const revenue = await wh.events.aggregate({
  workspace_id: "WORKSPACE_ID",
  function: "sum",
  field: "amount",
  event_category: "transaction",
  event_types: ["purchase"],
  time_window: "month",
});
console.log(revenue.data.value);

// Per-pass
const perPass = await wh.events.aggregateByPass({
  workspace_id: "WORKSPACE_ID",
  function: "sum",
  field: "amount",
  event_category: "transaction",
  time_window: "year",
});

// Convenience helpers
const total = await wh.events.getTotalTransactionAmount("WORKSPACE_ID", { time_window: "year" });
const count = await wh.events.getEventCount("WORKSPACE_ID", { event_category: "engagement" });