Events

Events record what happens to passes — field changes, transactions, engagement, loyalty changes, and pass-lifecycle moments. They power analytics, segment behavioral filters, and campaign results.

Auth: All event endpoints require a Bearer token (authentication is enforced inline). Authorization is workspace-scoped: each event is tied to a pass, and the service derives the pass's workspace and verifies the caller's membership.

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Event Categories

Every event has an event_category and a category-specific event_type:

Category	event_type values
field_change	field_updated, field_increment, field_decrement
transaction	purchase, refund (carry amount + currency)
engagement	check_in, check_out, visit, scan
loyalty	tier_promoted, tier_demoted, reward_redeemed, reward_cancelled, reward_used, points_earned, points_spent, points_expired, points_adjusted
pass_lifecycle	pass_installed, pass_uninstalled, pass_registered, template_changed

Event Structure

interface BaseEvent {
  id: string;
  workspace_id: string;
  client_id?: string;
  pass_id?: string;
  project_id?: string;
  pass_template_id?: string;
  event_category: 'field_change' | 'transaction' | 'engagement' | 'loyalty' | 'pass_lifecycle';
  event_type: string;
  event_timestamp: string;
  external_id?: string;   // your dedupe key
  source?: string;
  metadata?: Record<string, unknown>;
}

Category-specific fields: transaction adds amount + currency; field_change adds field_name + old_value/new_value; loyalty may carry amount.

Reference Pages

• Create — record a single event
• Batch — create or delete many events
• Query — list, get-by-id, per-pass, distinct types/sources
• Aggregate — count/sum/avg/min/max, optionally grouped

Endpoint Index

Method	Endpoint	Page
POST	/wallethero-api/events	create
POST	/wallethero-api/events/batch	batch
DELETE	/wallethero-api/events/batch	batch
POST	/wallethero-api/events/aggregate	aggregate
GET	/wallethero-api/events	query
GET	/wallethero-api/events/:id	query
GET	/wallethero-api/passes/:passId/events	query
GET	/wallethero-api/events/types	query
GET	/wallethero-api/events/sources	query

SDK Example

import { WalletHero } from "@wallethero/sdk";
const wh = new WalletHero({ apiToken: "YOUR_TOKEN" });

// Record a purchase
await wh.events.recordPurchase("PASS_ID", 49.99, "USD", {
  source: "pos-terminal-1",
  metadata: { order_id: "ORD-12345" },
});

// Query and aggregate
const events = await wh.events.list({ workspace_id: "WORKSPACE_ID", event_category: "transaction", limit: 50 });
const total = await wh.events.getTotalTransactionAmount("WORKSPACE_ID", { time_window: "year" });