Overview: How Live Pass Synchronization Works
Unlike static PDF tickets or image barcodes, digital wallet passes managed by Passinstance remain dynamically connected to the cloud after installation. Whenever a pass attribute, mechanic balance (stamps, loyalty points, prepaid currency), tier status, or template design changes, Passinstance orchestrates an asynchronous Wallet Propagation Pipeline that updates the live card on the customer's iPhone, Apple Watch, and Android device.
Wallet Propagation Status Lifecycle (walletVoidStatus / WalletPropagationStatus)
Every pass record tracks void/propagation status across Apple and Google cloud networks via Pass.walletVoidStatus (WalletPropagationStatus):
| Status Enum | Meaning & Operational State |
|---|---|
NONE | Pass has been created, or no wallet-visible propagation has been queued. |
PENDING | A field, mechanic balance, or void/template revision was committed; awaiting background job queue queue dispatch. |
QUEUED | Dispatched into the in-memory cache/background job queue wallet propagation worker queue for APNs and Google REST execution. |
SUCCEEDED | APNs push notification was accepted by Apple's HTTP/2 gateway (200 OK) and/or Google Wallet REST PATCH succeeded. |
FAILED | Propagation encountered an upstream error (e.g., expired Apple Pass Type certificate, revoked APNs token 410 Gone, or Google API quota error). |
Important: Publishing a template draft via
POST /api/v1/templates/:id/publishwithpropagateUpdates: truefans out propagation jobs across active passes bound to that template (filterable withactivePassesOnly: true). Always runGET /api/v1/templates/:id/publish-risk-checkbeforehand to inspect critical changes and potential impacts.
API Endpoints for Updating Passes
| Method | Endpoint Path | Description |
|---|---|---|
| PATCH | /api/v1/passes/:id | Updates custom attributes, status, expiration date, or barcode payload for a single pass and triggers wallet propagation. |
| POST | /api/v1/passes/upsert-by-external-id | Idempotently creates or updates an existing pass matched by (customerId, externalId) (PUT /api/v1/passes/by-external-id/:externalId also supported). |
| POST | /api/v1/batch-pass-operations/update | Updates selected passIds in a batch request (request payload) and enqueues propagation jobs. |
| POST | /api/v1/templates/:id/publish | Promotes a template draft (request payload with propagateUpdates: true) and refreshes active passes of that template. |
Example: Single Pass Update & Propagation Trigger
PATCH /api/v1/passes/c41a8d20-6e11-4f3b-9a81-0029d81a4f10
{
"attributes": {
"points": 1450,
"tier": "Platinum",
"nextReward": "Free Espresso"
},
"expirationDate": "2027-12-31 23:59"
}
Response (200 OK):
{
"id": "c41a8d20-6e11-4f3b-9a81-0029d81a4f10",
"externalId": "cust_884910",
"serialNumber": "PI-8849-2026-X9",
"status": "ACTIVE",
"lifecycleStatus": "ACTIVE",
"walletVoidStatus": "QUEUED",
"updatedAt": "2026-11-15T14:22:10.114Z"
}
Example: Batch Array Pass Update (request payload)
POST /api/v1/batch-pass-operations/update
{
"operation": "update",
"passIds": [
"c41a8d20-6e11-4f3b-9a81-0029d81a4f10",
"9b2f1e44-8a10-4c92-a711-5530e91b2c01"
],
"updateData": {
"attributes": {
"seasonalOffer": "Winter Bonus Points"
}
}
}
Why Sync Timing Can Vary Across Devices
-
Airplane Mode & Low Data Mode: iOS devices on Airplane Mode or Low Power Mode defer background APNs fetches until Wi-Fi or cellular connectivity resumes.
-
Manual Refresh Toggle: Customers who disabled Automatic Updates on the back of their Apple Wallet pass must pull down manually inside Apple Wallet to fetch the latest
.pkpassbundle. -
Voided Pass Suppression: By default, passes in
VOIDEDorEXPIREDstatus suppress routine marketing pushes unlessupdateVoidedExpiredPasses: trueis enabled on the template.
See Push Notifications, View & Update Passes, and Template Versions & Publishing for related workflows.
