EventsService

Track user activities and transactions.

Methods

Method	Description
create(data)	Create a single event
createBatch(events)	Create multiple events
list(options)	List events
listForPass(passId, options?)	List events for a pass
get(id)	Get a single event
aggregate(query)	Aggregate event data
getTypes(workspaceId)	Get distinct event types
getSources(workspaceId)	Get distinct event sources
deleteBatch(options)	Delete multiple events
recordPurchase(passId, data)	Record a purchase
recordRefund(passId, data)	Record a refund
recordCheckIn(passId, data)	Record a check-in
recordActivity(passId, data)	Record an activity
recordFieldChange(passId, data)	Record a field change

Convenience Methods

// Record a purchase transaction
await client.events.recordPurchase('pass-uuid', {
  amount: 49.99,
  currency: 'USD',
  source: 'pos-terminal-1',
  metadata: {
    order_id: 'ORD-12345',
    items: ['Coffee', 'Sandwich']
  }
});

// Record a refund
await client.events.recordRefund('pass-uuid', {
  amount: 10.00,
  currency: 'USD',
  metadata: { reason: 'Item out of stock' }
});

// Record a check-in
await client.events.recordCheckIn('pass-uuid', {
  source: 'store-downtown',
  metadata: { location: 'Main Entrance' }
});

// Record custom activity
await client.events.recordActivity('pass-uuid', {
  event_type: 'custom',
  source: 'mobile-app',
  metadata: { action: 'viewed_offers' }
});

// Record a field change
await client.events.recordFieldChange('pass-uuid', {
  field_name: 'points',
  old_value: '100',
  new_value: '150',
  source: 'loyalty-engine'
});

create()

Create a single event with full control.

await client.events.create({
  pass_id: 'pass-uuid',
  event_category: 'transaction',
  event_type: 'purchase',
  amount: 25.00,
  currency: 'USD',
  event_timestamp: '2024-01-15T14:30:00Z',
  external_id: 'ext-12345',
  source: 'website',
  metadata: {
    order_id: 'WEB-789',
    channel: 'online'
  }
});

createBatch()

Create up to 1000 events at once.

const result = await client.events.createBatch([
  {
    pass_id: 'pass-1',
    event_category: 'activity',
    event_type: 'check_in'
  },
  {
    pass_id: 'pass-2',
    event_category: 'transaction',
    event_type: 'purchase',
    amount: 15.00,
    currency: 'USD'
  }
]);

console.log(`Created: ${result.created}, Failed: ${result.failed}`);
if (result.errors) {
  console.log('Errors:', result.errors);
}

list() / listForPass()

Query events.

// List events for workspace
const events = await client.events.list({
  workspace_id: 'ws-uuid',
  event_category: 'transaction',
  limit: 50
});

// List events for specific pass
const passEvents = await client.events.listForPass('pass-uuid', {
  event_category: 'activity',
  limit: 20
});

aggregate()

Compute aggregated statistics.

// Total revenue this month
const revenue = await client.events.aggregate({
  workspace_id: 'ws-uuid',
  function: 'sum',
  field: 'amount',
  event_category: 'transaction',
  event_types: ['purchase'],
  time_window: 'month'
});
console.log(`Monthly revenue: $${revenue.value}`);

// Average transaction amount
const avgTransaction = await client.events.aggregate({
  workspace_id: 'ws-uuid',
  function: 'avg',
  field: 'amount',
  event_category: 'transaction',
  time_window: 'quarter'
});

// Check-in count this week
const checkins = await client.events.aggregate({
  workspace_id: 'ws-uuid',
  function: 'count',
  event_category: 'activity',
  event_types: ['check_in'],
  time_window: 'week'
});

// Per-pass totals
const topSpenders = await client.events.aggregate({
  workspace_id: 'ws-uuid',
  function: 'sum',
  field: 'amount',
  event_category: 'transaction',
  time_window: 'year',
  group_by_pass: true
});

Event Categories

Category	Types	Fields
transaction	purchase, refund, payment, charge, credit	amount, currency
activity	check_in, check_out, visit, scan, app_open, link_click, notification_received, notification_opened, pass_installed, pass_uninstalled, pass_registered, custom	-
field_change	field_updated, field_increment, field_decrement	field_name, old_value, new_value

Activity Event Types Reference

Type	Description	Use Case
check_in	Customer checks in at a location	Gym entries, store visits, event attendance
check_out	Customer checks out from a location	Gym departures, session end tracking
visit	General visit without formal check-in	Store browsing, location tracking
scan	Pass barcode/QR code scanned	POS lookups, access control
app_open	User opens the wallet app	App engagement tracking
link_click	User clicks a link on the pass	Web traffic attribution
notification_received	Push notification delivered	Delivery confirmation
notification_opened	User opens a notification	Engagement measurement
pass_installed	Pass added to wallet	Onboarding tracking
pass_uninstalled	Pass removed from wallet	Churn tracking
pass_registered	User completes registration	Signup funnel tracking
custom	Any custom activity type	Flexible tracking

Activity Event Examples

// Record a check-out (gym departure)
await client.events.recordActivity('pass-uuid', {
  event_type: 'check_out',
  source: 'gym-entrance',
  metadata: { duration_minutes: 75 }
});

// Record pass installation
await client.events.recordActivity('pass-uuid', {
  event_type: 'pass_installed',
  source: 'wallet-callback',
  metadata: { platform: 'apple_wallet' }
});

// Record notification opened
await client.events.recordActivity('pass-uuid', {
  event_type: 'notification_opened',
  source: 'push-service',
  metadata: { campaign_id: 'camp-123', notification_id: 'notif-456' }
});

// Record pass registration
await client.events.recordActivity('pass-uuid', {
  event_type: 'pass_registered',
  source: 'registration-form',
  metadata: { registration_source: 'website', referral_code: 'SUMMER2024' }
});

// Record link click
await client.events.recordActivity('pass-uuid', {
  event_type: 'link_click',
  source: 'pass-back-link',
  metadata: { link_url: 'https://example.com/offers', link_label: 'View Offers' }
});