Event Reference
Every event Pass Studio records across the life of a pass, the fields each one carries, and the name it has in each place you can receive it. Schema v1, September 2026.
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
| Event | Fires when | Webhook | Segment | Zapier |
|---|---|---|---|---|
viewed | A share page is opened in a browser, before any wallet action. | — | Pass Viewed | — |
downloaded | A pass is added to Apple Wallet or Google Wallet — from a share page, an installation email, a form, an API issue call, or a connected store. | pass.issued | Pass Installed | Pass Issued |
redownloaded | A holder who already has the pass adds it again. | — | Pass Reinstalled | — |
redeemed | A pass is redeemed on any channel: online checkout with the pass code, a Square register, a POS counter scan, the API, or a loyalty reward being used. | pass.redeemed | Pass Redeemed | Pass Redeemed |
removed | A holder deletes the pass from their wallet, or you revoke it. | pass.removed | Pass Removed | Pass Removed |
loyalty_issued | A loyalty pass is issued to a customer by the loyalty loop. | — | Loyalty Pass Issued | — |
loyalty_earned | Points are earned on a loyalty pass. | — | Loyalty Points Earned | — |
loyalty_reward_unlocked | A points balance crosses a reward threshold. | — | Loyalty Reward Unlocked | — |
loyalty_redeemed | A loyalty reward is used. | pass.redeemed | Pass Redeemed | Pass Redeemed |
journey_transition | A pass transforms into its next journey step after redemption. | — | Pass Journey Advanced | — |
order.processed | An order is fed through the order engine, from a connected store or the API. | — | Order Completed | — |
visited | A membership card scan is counted as a visit (one per holder per 60 minutes). | — | — | — |
member_updated | Staff edit or award something on one member's card. | — | — | — |
visited and member_updated belong to membership cards and surface on the member's timeline in the dashboard; they are not forwarded to marketing tools.
Webhook-only events
Two state changes are delivered to webhook endpoints but have no analytics row of their own:
| Webhook | Fires when | Zapier |
|---|---|---|
pass.updated | Field values or the barcode change on a pass or on one holder's instance, from Studio or the API. | — |
holder.merged | Two holder profiles are identified as the same customer and consolidated. | Holder Merged |
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.
| Field | Meaning |
|---|---|
passId | The pass the event belongs to. |
platform | apple, google, or web (web = browser-only events such as viewed). |
timestamp | UTC, ISO 8601. |
country, region, city | Derived from the request IP at the time of the event. Never stored on the holder. |
userAgent | The browser or wallet client that made the request. |
shareToken | The share link the holder came through, when there was one. |
utmSource, utmMedium, utmCampaign | The campaign parameters on this event's own touch. On counter and order redemptions the medium is pos or order and the campaign names the register location or the order. |
acqUtmSource, acqUtmMedium, acqUtmCampaign | First-touch acquisition: the campaign that produced the install, carried onto every later event for the same instance so a redemption can be attributed to the click that started it. |
serialNumber | The wallet serial of the instance, where the event is instance-scoped. |
metadata | Per-event detail, listed below. |
Per-event metadata
| Event | Keys |
|---|---|
downloaded | instanceId, serial, via (for example api_issue), viewport, language, and the full landing query string for lossless attribution. |
redeemed | instanceId plus locationId for counter scans; shopifyOrderId and discountCode for store orders. |
journey_transition | fromPassId, toPassId, instanceId, source. |
order.processed | source, orderRef, money, items[] — the replayable order stream. |
visited | instanceId, holderId, registerId. |
member_updated | changes[{key, from, to}], note, registerId. |
Webhook payloads add the holder's identity where known (email, phone, external IDs such as a Shopify customer ID). Segment payloads carry the same attribution fields under Segment's property names and can optionally include an anonymous persona with no PII. See each channel's page for the exact shape.
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 — the issued, redeemed, removed, and holder-merged triggers with no code. 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.
Questions?
Email support@thepassstudio.com or use the assistant in the bottom-right corner of the dashboard.