Skip to content
Help Center Guide · Pass ManagementOnboarding Phase 3
3 min readVerified 2026-11-16

View & Update Passes

Search issued passes with Saved Views and AND/OR filters, inspect device registrations, and edit holder attributes.

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 focus1 / 2
Key UI elements

Issued passes list & row actions (Zoomed)

Open the Passes tab to inspect issued test passes, filter by lifecycle or installation status, and access QR code, view, edit, and push notification actions.

Overview

Open Passes in the Dashboard (either in the global workspace directory or scoped inside a single template's Passes tab) or query /api/v1/passes to inspect, filter, audit, update, and migrate issued pass records in real time. Every mutation to a pass record's fields or template assignment automatically synchronizes to registered Apple Wallet and Google Wallet devices.

Passes search filters and row telemetry
Passes search filters and row telemetry

System Architecture: Pass Querying, Mutation & Template Switching

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
PASS QUERYING, PATCH MUTATION & TEMPLATE SWITCHING
STAGE 01 DASHBOARD FILTER BUILDER / REST API (/api/v1/passes)
Search & Filter: GET/api/v1/passes?templateId=...&status=ACTIVE&...
Partial Update: PATCH/api/v1/passes/:id
Audit & Timeline: GET/api/v1/passes/:id/history & /timeline
Template Switch: POST/api/v1/passes/:id/switch-template/:targetTemplateId
STAGE 02 DATABASE QUERY ENGINE & INDEXED ATTRIBUTES
Relational indexes on (customerId, templateId, status, externalId)
Sub-millisecond structured JSON filtering via high-speed search index attribute search index
Appends immutable field diff entries to pass audit log & Scan timeline
STAGE 03 WALLET PUSH PROPAGATION (WalletPropagationStatus)
Transitions propagation state: PENDINGQUEUEDSUCCEEDED
Apple Wallet: Dispatches APNs HTTP/2 wake pushdevice fetches new .pkpass
Google Wallet: Executes REST PATCH on cloud walletobjects resource

1. Searching & Filtering Passes (GET /api/v1/passes)

In the Dashboard, open Filters to combine AND / OR Condition Groups across system columns and custom structured JSON attributes, then save frequent queries as Saved Views:

  • Identity & Keys: serialNumber, externalId, bundleId, idempotencyKey, or pass id.
  • Lifecycle & Status: status (pass status), lifecycleStatus (PassLifecycleStatus), walletVoidStatus (WalletPropagationStatus), and artifact readiness (appleArtifactStatus, googleArtifactStatus).
  • Wallet Installation State: Installed, Not Installed, or Removed across Apple Wallet (iOS) and Google Wallet (Android) device registrations.
  • Date Windows: createdAt, updatedAt, expirationDate, and lastScannedAt range filters.
  • structured JSON Custom Attributes (attribute search index): High-speed containment and comparison filters against any key inside pass.attributes (for example, attributes.memberTier = "VIP" or attributes.pointsBalance >= 1000).
Advanced filters drawer with AND/OR condition builder
Advanced filters drawer with AND/OR condition builder

Example: Query Passes & Look Up by External ID

  • GET /api/v1/passes?templateId=tmpl_01hxyz987654321&status=ACTIVE&externalId=crm_usr_44910&page=1&limit=25
  • GET /api/v1/passes/by-external-id/crm_usr_44910 (returns the live non-deleted pass matching externalId directly without storing internal UUIDs externally)
Headers
X-API-Key <API_KEY>

2. Updating an Individual Pass (PATCH /api/v1/passes/:id)

Updating a pass merges new values into attributes, adjusts expirationDate or barcodeValue, and queues an immediate push update to all devices where the pass is installed. If a modified field has a changeMessage containing %@ configured on the template, Apple Wallet displays a native lock-screen alert.

HTTP Request

PATCH /api/v1/passes/pass_01j8k9m2n3p4q5r6 Headers: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "attributes": {
    "pointsBalance": 1450,
    "memberTier": "Platinum"
  },
  "barcodeAltText": "44910-PLATINUM",
  "expirationDate": "2028-12-31 23:59"
}

HTTP Response (200 OK)

JSON
{
  "success": true,
  "data": {
    "id": "pass_01j8k9m2n3p4q5r6",
    "serialNumber": "PI-GOLD-2026-44910",
    "externalId": "crm_usr_44910",
    "bundleId": null,
    "status": "ACTIVE",
    "lifecycleStatus": "ACTIVE",
    "walletVoidStatus": "QUEUED",
    "attributes": {
      "firstName": "Marcus",
      "lastName": "Vance",
      "email": "marcus.vance@example.com",
      "pointsBalance": 1450,
      "memberTier": "Platinum"
    },
    "updatedAt": "2026-11-15T17:30:00.000Z"
  },
  "statusCode": 200
}

3. Auditing Pass History & Event Timeline

Passinstance tracks two complementary audit streams for every pass record:

EndpointScope & Returned Data
GET /api/v1/passes/:id/historyReturns chronological field and attribute mutations (previousValue, newValue, changedBy, `source: 'API' \'SCANNER' \'DASHBOARD' \'WORKFLOW', timestamp`).
GET /api/v1/passes/:id/timelineReturns the unified lifecycle and engagement stream, combining pass creation, email/SMS delivery events, Apple/Google device installations, scanner validations, balance adjustments, and push notifications.

Example: Fetch Pass Timeline

GET /api/v1/passes/pass_01j8k9m2n3p4q5r6/timeline
JSON
{
  "success": true,
  "data": {
    "passId": "pass_01j8k9m2n3p4q5r6",
    "events": [
      {
        "eventId": "evt_03",
        "type": "ATTRIBUTE_UPDATED",
        "summary": "pointsBalance changed from 500 to 1450",
        "actor": "api_key:pi_live_99a8",
        "createdAt": "2026-11-15T17:30:00.000Z"
      },
      {
        "eventId": "evt_02",
        "type": "WALLET_INSTALLED",
        "platform": "APPLE_WALLET",
        "deviceLibraryIdentifier": "dlib_8841209a",
        "createdAt": "2026-11-15T15:10:05.000Z"
      },
      {
        "eventId": "evt_01",
        "type": "PASS_CREATED",
        "summary": "Pass issued via REST API",
        "createdAt": "2026-11-15T15:04:12.000Z"
      }
    ]
  },
  "statusCode": 200
}

4. Live Template Migration (POST /api/v1/passes/:id/switch-template/:targetTemplateId)

When a customer upgrades to a new tier design or transitions between seasonal programs, you can migrate an existing pass to a different PUBLISHED template without changing the pass's id, serialNumber, authenticationToken, or active device registrations.

POST /api/v1/passes/pass_01j8k9m2n3p4q5r6/switch-template/tmpl_platinum_vip_999 Headers: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "preserveAttributes": true,
  "attributeOverrides": {
    "vipLoungeAccess": "Unlimited"
  },
  "pushUpdateImmediately": true
}

Important: To switch a pass to :targetTemplateId seamlessly on Apple Wallet devices, both the source template and the target template must share the same Apple passTypeIdentifier (Pass Type ID Certificate). If the target template uses a different Pass Type ID, iOS treats it as a separate card rather than an in-place visual replacement.

For state transitions and voiding rules, see Pass Lifecycle & Statuses. For multi-record updates, see Bulk Operations.

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.