Events — Create

Record a single event for a pass. The request body is a discriminated union on event_category, so the required fields depend on the category.

Auth: Bearer token. The event is tied to pass_id; the service derives the pass's workspace and checks the caller's membership.

---

Create Event

POST /wallethero-api/events

Creates one event.

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

Request Body (common fields)

Field	Type	Required	Default	Description
event_category	string	Yes	—	One of field_change, transaction, engagement, loyalty, pass_lifecycle
pass_id	string (UUID)	Yes	—	Pass the event belongs to
event_type	string	Yes*	—	Category-specific type (see below). Optional for field_change (defaults to field_updated)
event_timestamp	string (ISO 8601)	No	now	When the event occurred
external_id	string (≤255)	No	—	Your dedupe key
source	string (≤100)	No	—	Event source (e.g. pos-terminal-1)
metadata	object	No	—	Arbitrary JSON

Category-Specific Fields

field_change — event_type ∈ field_updated (default), field_increment, field_decrement

Field	Type	Required	Description
field_name	string (1–100)	Yes	Name of the changed field
old_value	string | null	No	Previous value (as string)
new_value	string | null	No	New value (as string)

transaction — event_type ∈ purchase, refund

Field	Type	Required	Description
amount	number	Yes	Transaction amount
currency	string (3)	Yes	ISO 4217 currency code (e.g. USD)

engagement — event_type ∈ check_in, check_out, visit, scan (no extra fields)

loyalty — event_type ∈ tier_promoted, tier_demoted, reward_redeemed, reward_cancelled, reward_used, points_earned, points_spent, points_expired, points_adjusted

Field	Type	Required	Description
amount	number	No	Points/value delta, where applicable

pass_lifecycle — event_type ∈ pass_installed, pass_uninstalled, pass_registered, template_changed

Field	Type	Required	Description
field_name	string (1–100)	No	Relevant field (e.g. for template_changed)
old_value	string | null	No	Previous value
new_value	string | null	No	New value

Example: Transaction Event

curl -X POST "https://api.wallethero.app/wallethero-api/events" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_category": "transaction",
    "pass_id": "PASS_ID",
    "event_type": "purchase",
    "amount": 49.99,
    "currency": "USD",
    "source": "online-store",
    "metadata": { "order_id": "ORD-12345" }
  }'

Example: Engagement Event

curl -X POST "https://api.wallethero.app/wallethero-api/events" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_category": "engagement",
    "pass_id": "PASS_ID",
    "event_type": "check_in",
    "source": "store-001"
  }'

Example: Field Change Event

curl -X POST "https://api.wallethero.app/wallethero-api/events" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_category": "field_change",
    "pass_id": "PASS_ID",
    "event_type": "field_increment",
    "field_name": "points",
    "old_value": "1000",
    "new_value": "1050"
  }'

Response (200)

{
  "data": {
    "id": "event-uuid",
    "workspace_id": "WORKSPACE_ID",
    "pass_id": "PASS_ID",
    "event_category": "transaction",
    "event_type": "purchase",
    "amount": 49.99,
    "currency": "USD",
    "event_timestamp": "2026-01-15T14:30:00Z",
    "source": "online-store",
    "metadata": { "order_id": "ORD-12345" }
  }
}

SDK

// Generic
await wh.events.create({
  event_category: "transaction",
  pass_id: "PASS_ID",
  event_type: "purchase",
  amount: 49.99,
  currency: "USD",
});

// Convenience helpers
await wh.events.recordPurchase("PASS_ID", 49.99, "USD", { source: "online-store" });
await wh.events.recordCheckIn("PASS_ID", { source: "store-001" });
await wh.events.recordFieldChange("PASS_ID", "points", "1000", "1050", {
  event_type: "field_increment",
});

Errors

Status	Code	Description
400	INVALID_PAYLOAD	Missing or invalid fields for the category
403	FORBIDDEN	Not authenticated, or not a member of the pass's workspace
404	RECORD_NOT_FOUND	Pass not found