Event Reference

The lifecycle

A pass is viewed when someone opens its share page, installed when it lands in a wallet, redeemed when its code is used on any channel, and removed when the holder deletes it or you revoke it. Loyalty passes add earned and reward unlocked between install and redemption. A pass with a journey adds a transition after redemption, when it transforms into the next step instead of going gray.

Every event is written once, to one stream, and the same record is what feeds the Analytics dashboard, your webhook endpoints, your Segment workspace, and your Zaps. The names differ by channel because each follows its own convention; the table below is the map between them.

Events

visited and member_updated belong to membership cards and surface on the member's timeline in the dashboard. Since 2026-10-24 both reach Segment, as Member Visited and Member Updated (the Segment page states what each carries in each privacy mode), and both fire a webhook — holder.visited, and holder.updated with every changed field's before and after values and the staff note in full — with the Zapier triggers Holder Visited and Holder Updated (app 1.0.19). A member_updated that changes points on a membership card with no loyalty program also fires holder.points_changed; a program-backed award fires it from loyalty_earned instead, so one award is one points event. Shopify Flow receives them as Visit counted and Points changed.

Webhook-only events

Two state changes are delivered to webhook endpoints but have no analytics row of their own:

Wallet plumbing

Apple Wallet also produces register, unregister, and fetch events as devices subscribe to updates and pull new versions of a pass. They are recorded for operations and support and are deliberately not forwarded to any channel: they would be noise in a marketing workspace. The install signal you want is downloaded.

Fields

Every event carries the same core fields. Not every field is set on every event.

Per-event metadata

Webhook payloads add the holder's identity where known (email, phone, external IDs such as a Shopify customer ID). Segment receives a fixed set of these fields under Segment's property names, with the holder as userId; the complete property-by-property list, the identity rules and example payloads are on the Segment page.

Getting events out

• Signed webhooks — real-time push to your own endpoint, HMAC-signed, queued with retries, identity-enriched. Best for CRM sync and anything that must react within seconds. Webhooks reference →
• Segment — every event as a Segment track call with first-touch attribution, and from there to GA4, Mixpanel, Amplitude, Adobe Analytics, or a warehouse. Best for analytics and attribution. Segment integration →
• Zapier — eleven triggers with no code: issued, updated, redeemed, removed, holder merged, tier changed, points changed, reward unlocked, journey advanced, visited and holder updated. Best for spreadsheets, email tools, and one-off automations. Zapier integration →
• REST API — pull the current state rather than the event stream: a holder's passes and points, a pass's instances, field values. Best for lookups at the moment you need them. API reference →
• Analytics dashboard — views, installs, redemptions, and removals per pass, by platform and campaign, with no setup.

Landing events in your warehouse

Connect Segment and add a warehouse destination (BigQuery, Snowflake, Redshift, Postgres, or Databricks). Segment creates one table per event using its snake-case convention, so Pass Installed becomes pass_installed and Pass Redeemed becomes pass_redeemed, each with the fields above as columns. A redemption joined to its install on instanceId or the acquisition fields gives you click-to-redemption attribution in plain SQL. For a lower-volume alternative, point a webhook endpoint at a function that writes rows directly.

Privacy

Location fields are derived from the request IP at event time and are never written back to the holder. Individual events are kept for a bounded period and then aggregated; redaction requests remove holder identity from the records they cover. Retention periods, redaction behavior, and where the data lives are on the Security & data page.

Versioning

This is schema v1. Changes are additive: new events and new fields may appear, existing names and meanings do not change. A breaking change would ship as a new version with notice on this page.

Changelog

• September 2026 — v1 published: the events, fields, and channel names documented on this page.
• 2026-10-23 — additive: order.processed carries holderId and serial in metadata and the acqUtm* / acqPartnerId / acqClickId columns when the order reached one holder's own card; redeemed from an online order carries holderId and serial under the same rule; every loyalty event and tier_changed carry holderId (the holder) next to loyaltyHolderId (the program member record) and serial; utmContent and utmTerm are forwarded to Segment. No existing name or meaning changed.
• 2026-10-24 — additive: journey_transition carries holderId and serial in metadata and the acqUtm* / acqPartnerId / acqClickId columns when the card that moved is one holder's own; the six tier details on tier_changed (direction, tierIndex, tierTitle, previousTierIndex, block, blockEarned) are forwarded to Segment as properties of Loyalty Tier Changed; visited and member_updated carry holderId, serial and the acquisition columns, visited adds registerName and visitCount, member_updated from the staff app adds registerName, and both are forwarded to Segment as Member Visited and Member Updated. Five webhook events are mapped from this stream — holder.points_changed (from loyalty_earned, and from member_updated when it changes points on a membership card with no loyalty program), holder.reward_unlocked, pass.journey_advanced, holder.visited, holder.updated — each with a Zapier trigger (app 1.0.19); the four loyalty events carry instanceId in metadata. No existing name or meaning changed. On a shared simple-mode code, redeemed and order.processed carry holderId, serial and the acquisition columns only when the order email matches exactly one active card of the pass; otherwise none, never another holder's.
• 2026-10-29 — additive: the award that reaches the reward threshold now publishes loyalty_earned (with thresholdReached: true) right before loyalty_reward_unlocked, so holder.points_changed, Shopify Flow's Points changed, Segment's Loyalty Points Earned and the loyalty activity report's Points earned total see every balance change. Before this date that award produced only loyalty_reward_unlocked; for older rows its earned and balance fields hold the change. A redemption order is unchanged in the stream: one loyalty_redeemed row; since the same date that row also fires holder.points_changed for the points the order earned (delta = earned, reason "reward", the order id), as Shopify Flow's Points changed already read it; a redemption that earned nothing fires no points event. From the same date a manual award with no order (API, Studio, staff app, campaign bonus) on a program card past the welcome state carries delta, manualAdjust: true and the caller's reason and no shopifyOrderId, as the welcome-state and deduction path always did; before, such an award ran as a synthetic order and carried the claim key <team>_api_points_<holder> as shopifyOrderId with no reason, so holder.points_changed and Flow's Points changed read reason "order". No existing name or meaning changed.

Questions?

Email support@thepassstudio.com or use the assistant in the bottom-right corner of the dashboard.