EventsService

Use client.events for event ingestion, queries, and aggregates.

Methods

Method	Purpose
create(data)	Create one event
createBatch(events)	Create up to 1,000 events
get(id)	Read one event
deleteBatch(eventIds, workspaceId)	Delete selected events
list(query)	Query events
getByPass(passId, options?)	Query one pass's events
aggregate(query)	Aggregate events
aggregateByPass(query)	Aggregate and group by pass
getEventTypes(workspaceId)	List event types in use
getSources(workspaceId)	List event sources in use

Convenience methods

await client.events.recordPurchase("pass-uuid", 25, "PLN", {
  external_id: "receipt-1842",
  source: "pos",
  metadata: { store: "Downtown" },
});

await client.events.recordRefund("pass-uuid", 10, "PLN");

await client.events.recordCheckIn("pass-uuid", {
  source: "store-downtown",
});

Other helpers include recordTransaction(), recordVisit(), recordFieldChange(), recordActivity(), recordPointsEarned(), and recordPointsRedeemed().

Query

const events = await client.events.list({
  workspace_id: "workspace-uuid",
  client_id: "client-uuid",
  event_category: "transaction",
  event_types: ["purchase"],
  from_date: "2026-08-01T00:00:00.000Z",
  limit: 100,
});

Event categories are field_change, transaction, engagement, loyalty, pass_lifecycle, integration, and referral.

For normalized commerce records that trigger transaction-domain side effects, use client.transactions.create().