Skip to content
Help Center GuideOnboarding Phase 6
4 min readVerified 2026-11-16

Pass Issuance & Usage Metrics

Interpret Passes Created, Active in Wallets, Not Installed, Removed from Wallets, and multi-device Apple registration math.

In This Guide

Interactive UI Walkthroughs

Open in 6-Phase Onboarding Guide

Inspect exact dashboard panels, controls, and zoomed callouts related to this guide.

Zoomed UI focus
Key UI elements

Pass health & Recommended actions (Zoomed)

Track the active vs. uninstalled ratio in Pass health and act on automated recommendations such as following up on passes awaiting wallet installation.

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

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
PASS INSTANCE VS. DEVICE REGISTRATION TAXONOMY
STAGE 01
1
LOGICAL PASS INSTANCE LAYER (1 Pass Record = 1 Unique serialNumber) [ Pass Created ]+[ Unclaimed (unclaimedPasses) ] (0 Registrations) (totalPasses)
+[ Active (activePasses) ] (>= 1 Active Reg) +[ Removed (inactivePasses) ] (All Regs Removed) +[ Terminal (expiredPasses / voidedPasses) ]
STAGE 02
Apple Wallet Ecosystem (APNs)
Passholder iPhone (Reg #1)
Paired Apple Watch (Reg #2)
1 Active Pass = 2 Device Regs
Google Wallet Ecosystem (REST)
PassObject Linked to Google ID
Save / Remove Callback Sync
1 Active Pass = 1 Object Reg
2
PHYSICAL DEVICE REGISTRATION LAYER (installedDevices across uniqueDevices)

Important: In GET /api/v1/analytics/wallet-installations, a single pass installed on both a customer's iPhone and Apple Watch counts as 1 activePasses in the Pass Instance summary, while recording 2 installedDevices in the Device Registration summary because APNs delivers push notifications to each device token independently.

Canonical Metric Definitions (metric-definitions.ts)

Pass Instance Metrics

Metric KeyDashboard LabelTechnical Definition & Evaluation Basis
totalPassesTotal Passes IssuedTotal pass records issued and not deleted at snapshot time.
activePassesActive PassesLive pass instances that currently have at least one reachable device registration (excludes expired and voided passes in standard pass overview).
inactivePassesRemoved PassesLive pass instances previously saved to a wallet that no longer have any reachable device registrations (removedPasses in installation reports).
unclaimedPassesUnclaimed PassesLive pass instances issued via API, CSV, or PassFlow that have never been saved to a device wallet (noRegistrationPasses).
expiredPassesExpired PassesPass instances whose expirationDate has passed or whose status is marked EXPIRED.
voidedPassesVoided PassesPass instances revoked or voided server-side via dashboard, workflow, or VOIDED_AFTER_SCAN scan mode.

Device Registration Metrics

Metric KeyDashboard LabelTechnical Definition & Evaluation Basis
installedDevicesActive Device RegistrationsTotal reachable saved pass registrations across all physical devices (1 pass on 2 devices = 2).
inactiveDeviceRegistrationsRemoved Device RegistrationsSaved pass registrations that were unregistered by the device or invalidated via permanent APNs push failure.
totalDeviceRegistrationsTotal Device RegistrationsCumulative saved pass registrations across both active and removed states.
uniqueDevicesUnique DevicesDistinct physical device hardware identifiers currently holding at least one active pass registration.
devicePlatformDistributionDevice Platform DistributionBreakdown 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 calls DELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber or Google Wallet dispatches a removal callback, plus inferred removals when APNs returns 410 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

EndpointHTTP VerbDescription
/api/v1/analytics/passes/overviewGETSnapshot of totalPasses, activePasses, inactivePasses, unclaimedPasses, expiredPasses, and voidedPasses.
/api/v1/analytics/passes/createdGETTime-series of newly created pass instances bucketed by day, week, or month.
/api/v1/analytics/registrationsGETTime-series of active and deactivated device registrations over the selected window.
/api/v1/analytics/wallet-installationsGETComprehensive matrix separating pass-level installation states from device-level registration events.

Example: Detailed Wallet Installation Matrix

HTTP
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>
JSON
{
  "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
  }
}

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.