Skip to content
Help Center Guide · Wallet Updates & Notifications
3 min readVerified 2026-11-16

Update Existing Passes

Understand how server-side field edits trigger Apple APNs silent updates and Google Wallet REST object patches on live phones.

In This Guide

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.

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
WALLET UPDATE & PROPAGATION PIPELINE
STAGE 01 MUTATION TRIGGER SOURCES
Single Update: PATCH/api/v1/passes/:id or POST/api/v1/passes/upsert-by-external-id
Batch Array Update: POST/api/v1/batch-pass-operations/update
Template Publish: POST/api/v1/templates/:id/publish (propagateUpdates: true)
Scanner / POS: POST/api/v1/scans / POST/v1/pos/redeem / /api/v1/reader/redeem
STAGE 02 DATABASE COMMIT & PROPAGATION STATE TRANSITION
1
Increment pass revision & record pass audit log audit log
2
Set walletVoidStatus (WalletPropagationStatus): NONEPENDINGQUEUED
3
Enqueue background job queue propagation job (wallet-propagation queue)
Apple Wallet Device Registrations
STAGE 03A
1
Apple Push Delivery sends HTTP/2 emp push {} to each registered device
2
iOS wakes & polls:GET/v1/devices/.../registrations
3
iOS fetches signed .pkpass:GET/v1/passes/:typeId/:serial
Google Wallet Cloud Object
STAGE 03B
1
Google Wallet Sync executes authenticated REST PATCH on walletobjects/v1/...
2
Google Cloud pushes updated object state directly to Android devices via Google Play Services
STAGE 04 FINAL TELEMETRY & PROPAGATION STATUS UPDATE
walletVoidStatus (WalletPropagationStatus): SUCCEEDED or FAILED

Wallet Propagation Status Lifecycle (walletVoidStatus / WalletPropagationStatus)

Every pass record tracks void/propagation status across Apple and Google cloud networks via Pass.walletVoidStatus (WalletPropagationStatus):

Status EnumMeaning & Operational State
NONEPass has been created, or no wallet-visible propagation has been queued.
PENDINGA field, mechanic balance, or void/template revision was committed; awaiting background job queue queue dispatch.
QUEUEDDispatched into the in-memory cache/background job queue wallet propagation worker queue for APNs and Google REST execution.
SUCCEEDEDAPNs push notification was accepted by Apple's HTTP/2 gateway (200 OK) and/or Google Wallet REST PATCH succeeded.
FAILEDPropagation 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/publish with propagateUpdates: true fans out propagation jobs across active passes bound to that template (filterable with activePassesOnly: true). Always run GET /api/v1/templates/:id/publish-risk-check beforehand to inspect critical changes and potential impacts.

API Endpoints for Updating Passes

MethodEndpoint PathDescription
PATCH/api/v1/passes/:idUpdates custom attributes, status, expiration date, or barcode payload for a single pass and triggers wallet propagation.
POST/api/v1/passes/upsert-by-external-idIdempotently 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/updateUpdates selected passIds in a batch request (request payload) and enqueues propagation jobs.
POST/api/v1/templates/:id/publishPromotes a template draft (request payload with propagateUpdates: true) and refreshes active passes of that template.

Example: Single Pass Update & Propagation Trigger

JSON
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):

JSON
{
  "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)

JSON
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 .pkpass bundle.
  • Voided Pass Suppression: By default, passes in VOIDED or EXPIRED status suppress routine marketing pushes unless updateVoidedExpiredPasses: true is enabled on the template.

See Push Notifications, View & Update Passes, and Template Versions & Publishing for related workflows.

Related Product & Developer Documentation

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.