Overview
Accurate interpretation of wallet telemetry requires a strict architectural distinction between Pass Instances (logical credential records issued in the database and keyed by UUID id, serialNumber, and optional upstream externalId) and Device Registrations (physical mobile or wearable devices actively storing those credentials against the template's Apple bundleId / passTypeIdentifier or Google Wallet Object ID).
Passinstance enforces this separation in metric-definitions.ts (PASS_ANALYTICS_METRIC_DEFINITIONS and WALLET_INSTALLATION_METRIC_DEFINITIONS), surfaced visually in Dashboard Analytics -> Passes (/analytics/passes) and via /api/v1/analytics/*, so marketing teams and billing administrators never conflate generated links with installed wallet cards.
Architectural Separation: Pass Instances vs. Device Registrations
Important: In
GET /api/v1/analytics/wallet-installations, a single pass installed on both a customer's iPhone and Apple Watch counts as 1activePassesin the Pass Instance summary, while recording 2installedDevicesin the Device Registration summary because APNs delivers push notifications to each device token independently.
Canonical Metric Definitions (metric-definitions.ts)
Pass Instance Metrics
| Metric Key | Dashboard Label | Technical Definition & Evaluation Basis |
|---|---|---|
totalPasses | Total Passes Issued | Total pass records issued and not deleted at snapshot time. |
activePasses | Active Passes | Live pass instances that currently have at least one reachable device registration (excludes expired and voided passes in standard pass overview). |
inactivePasses | Removed Passes | Live pass instances previously saved to a wallet that no longer have any reachable device registrations (removedPasses in installation reports). |
unclaimedPasses | Unclaimed Passes | Live pass instances issued via API, CSV, or PassFlow that have never been saved to a device wallet (noRegistrationPasses). |
expiredPasses | Expired Passes | Pass instances whose expirationDate has passed or whose status is marked EXPIRED. |
voidedPasses | Voided Passes | Pass instances revoked or voided server-side via dashboard, workflow, or VOIDED_AFTER_SCAN scan mode. |
Device Registration Metrics
| Metric Key | Dashboard Label | Technical Definition & Evaluation Basis |
|---|---|---|
installedDevices | Active Device Registrations | Total reachable saved pass registrations across all physical devices (1 pass on 2 devices = 2). |
inactiveDeviceRegistrations | Removed Device Registrations | Saved pass registrations that were unregistered by the device or invalidated via permanent APNs push failure. |
totalDeviceRegistrations | Total Device Registrations | Cumulative saved pass registrations across both active and removed states. |
uniqueDevices | Unique Devices | Distinct physical device hardware identifiers currently holding at least one active pass registration. |
devicePlatformDistribution | Device Platform Distribution | Breakdown of active device registrations by wallet ecosystem (APPLE_WALLET vs. GOOGLE_WALLET) and OS family. |
Wallet Telemetry Nuances & Edge Cases
In addition to confirmed states, the GET /api/v1/analytics/wallet-installations report tracks event-level transitions and edge states:
-
installEvents(Wallet Installs): Device registrations created during the reporting period, counted once per unique pass-and-device pair. Reinstalling an already registered pass on the same device does not inflate the install count. -
removalEvents(Wallet Removals): Recorded when Apple Wallet callsDELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumberor Google Wallet dispatches a removal callback, plus inferred removals when APNs returns410 Unregistered. -
otherStatePasses(Unresolved Registrations): Passes whose only registrations are pending, suspended, or in an indeterminate state that proves neither an active installation nor a confirmed removal. -
noRegistrationPasses(No Confirmed Installation): Passes with zero registration records. For Apple Wallet, installation always triggers an immediate device registration call; for Google Wallet, installation relies on save callbacks.
Core Issuance & Registration API Endpoints
| Endpoint | HTTP Verb | Description |
|---|---|---|
/api/v1/analytics/passes/overview | GET | Snapshot of totalPasses, activePasses, inactivePasses, unclaimedPasses, expiredPasses, and voidedPasses. |
/api/v1/analytics/passes/created | GET | Time-series of newly created pass instances bucketed by day, week, or month. |
/api/v1/analytics/registrations | GET | Time-series of active and deactivated device registrations over the selected window. |
/api/v1/analytics/wallet-installations | GET | Comprehensive matrix separating pass-level installation states from device-level registration events. |
Example: Detailed Wallet Installation Matrix
GET /api/v1/analytics/wallet-installations?range=last_30days&templateId=b4f29c10-83e1-4a7b-9d12-56e8012a9c04 HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
{
"snapshotAt": "2026-11-15T23:59:59.999Z",
"passes": {
"totalPasses": 5000,
"activePasses": 3850,
"removedPasses": 310,
"otherStatePasses": 15,
"noRegistrationPasses": 825
},
"registrations": {
"installedDevices": 4290,
"inactiveDeviceRegistrations": 365,
"totalDeviceRegistrations": 4655,
"uniqueDevices": 4180,
"devicePlatformDistribution": {
"apple": 2910,
"google": 1380
}
},
"periodEvents": {
"passesCreated": 640,
"installEvents": 595,
"removalEvents": 42
}
}
Related Documentation
-
Understand how active pass counts apply to subscription tiers in Active Passes & Usage Limits.
-
Explore workspace chart controls in Analytics Dashboard.
