Events — Query

Retrieve events: list with filters, fetch one by ID, list a single pass's events, and discover the distinct event types and sources in a workspace.

Auth: Bearer token. The service resolves the workspace from workspace_id / pass_id / client_id in the query (or the pass for the per-pass route) and checks the caller's membership.

---

List Events

GET /wallethero-api/events

Lists events matching the filters, newest first, paginated. Scope by workspace_id (or pass_id / client_id) so membership can be verified.

Auth: Bearer token — workspace member.

Query Parameters

Parameter	Type	Required	Default	Description
workspace_id	string (UUID)	No*	—	Workspace filter (one scope is required for auth)
client_id	string (UUID)	No	—	Filter by client
pass_id	string (UUID)	No	—	Filter by pass
project_id	string (UUID)	No	—	Filter by project
pass_template_id	string (UUID)	No	—	Filter by template
event_category	string	No	—	One of field_change, transaction, engagement, loyalty, pass_lifecycle
event_types	string (CSV)	No	—	Comma-separated event types
field_name	string (≤100)	No	—	Filter field_change events by field name
source	string (≤100)	No	—	Filter by source
from_date	string (ISO 8601)	No	—	On/after this time
to_date	string (ISO 8601)	No	—	On/before this time
limit	number	No	100	Max results (1–1000)
offset	number	No	0	Pagination offset

* Provide at least one of workspace_id, pass_id, or client_id so the workspace can be resolved for the access check.

Example Request

curl "https://api.wallethero.app/wallethero-api/events?workspace_id=WORKSPACE_ID&event_category=transaction&limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{
  "data": [
    { "id": "event-1", "pass_id": "pass-1", "event_category": "transaction", "event_type": "purchase", "amount": 49.99, "currency": "USD", "event_timestamp": "2026-01-15T14:30:00Z" }
  ],
  "meta": { "total_count": 150, "returned_count": 50, "offset": 0 }
}

SDK

const events = await wh.events.list({
  workspace_id: "WORKSPACE_ID",
  event_category: "transaction",
  limit: 50,
});

---

Get Event by ID

GET /wallethero-api/events/:id

Fetches a single event.

Auth: Bearer token — workspace member (derived from the event's pass).

Path Parameters

Parameter	Type	Description
id	string (UUID)	Event identifier

Example Request

curl "https://api.wallethero.app/wallethero-api/events/EVENT_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{
  "data": { "id": "EVENT_ID", "pass_id": "pass-1", "event_category": "transaction", "event_type": "purchase", "amount": 49.99, "currency": "USD" }
}

SDK

const event = await wh.events.get("EVENT_ID");

---

Get Events for a Pass

GET /wallethero-api/passes/:passId/events

Lists events for a single pass, newest first, paginated.

Auth: Bearer token — workspace member (derived from the pass).

Path Parameters

Parameter	Type	Description
passId	string (UUID)	Pass identifier

Query Parameters

Parameter	Type	Required	Default	Description
event_category	string	No	—	Filter by category
limit	number	No	100	Max results (1–1000)
offset	number	No	0	Pagination offset

Example Request

curl "https://api.wallethero.app/wallethero-api/passes/PASS_ID/events?event_category=transaction&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{
  "data": [
    { "id": "event-1", "pass_id": "PASS_ID", "event_category": "transaction", "event_type": "purchase", "amount": 49.99, "currency": "USD" }
  ],
  "meta": { "total_count": 12, "returned_count": 12, "offset": 0 }
}

SDK

const passEvents = await wh.events.getByPass("PASS_ID", {
  event_category: "transaction",
  limit: 20,
});

---

List Distinct Event Types

GET /wallethero-api/events/types

Returns the distinct event types present in a workspace, grouped by category.

Auth: Bearer token — workspace member (the workspace_id query param).

Query Parameters

Parameter	Type	Required	Description
workspace_id	string (UUID)	Yes	Workspace identifier

Example Request

curl "https://api.wallethero.app/wallethero-api/events/types?workspace_id=WORKSPACE_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{
  "data": [
    { "category": "transaction", "types": ["purchase", "refund"] },
    { "category": "engagement", "types": ["check_in", "visit"] }
  ]
}

SDK

const types = await wh.events.getEventTypes("WORKSPACE_ID");

---

List Distinct Sources

GET /wallethero-api/events/sources

Returns the distinct source values present in a workspace.

Auth: Bearer token — workspace member (the workspace_id query param).

Query Parameters

Parameter	Type	Required	Description
workspace_id	string (UUID)	Yes	Workspace identifier

Example Request

curl "https://api.wallethero.app/wallethero-api/events/sources?workspace_id=WORKSPACE_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{ "data": ["pos-terminal-1", "online-store", "mobile-app"] }

SDK

const sources = await wh.events.getSources("WORKSPACE_ID");