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

Push Notifications

Send lock-screen change alerts on iOS (via changeMessage) and Android without SMS per-message costs, plus location triggers.

In This Guide

Overview: How Wallet Lock-Screen Push Notifications Work

Apple Wallet and Google Wallet do not allow arbitrary unlinked push popups like standalone native apps; instead, lock-screen notifications are governed by strict cryptographic wallet protocols tied directly to field value mutations on an installed pass. When a pass field changes, both platforms surface a native lock-screen alert with zero per-message SMS gateway fees.

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
APPLE APNs & GOOGLE WALLET PUSH PROTOCOL
STAGE 01 PHASE 1: INITIAL DEVICE REGISTRATION (iOS)
iPhone installs .pkpassCalls Passinstance Apple Web Service:POST/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeId/:serial
Header: Authorization: ApplePass <authenticationToken>
Body: { "pushToken": "<apns_device_hex_token>" }
STAGE 02 PHASE 2: PUSH NOTIFICATION DISPATCH TRIGGER
POST/api/v1/push-notifications/passes/:id | /templates/:id/send | /segmentation
Apple APNs HTTP/2 Protocol
STAGE 03A
1
Apple Push Delivery opens TLS HTTP/2 to api.push.apple.com:443 signed with Pass Type Certificate (topic)
2
Sends empty payload {} (<4096 B)
3
iPhone wakes & queries changed list:GET/v1/devices/...?passesUpdated
4
iPhone pulls updated .pkpass viaGET/v1/passes/:passTypeId/:serial
5
iOS diffs old vs new pass.json & fires changeMessage: "... %@"
Google Wallet REST API Protocol
STAGE 03B ream| | 1. Google Wallet Sync issue
PATCH or addMessage on walletobjects/v1/...
2
Sets notifyPreference: NOTIFY_ON_UPDATE
3
Google Play Services renders native Android lock-screen wallet notification

Apple Wallet Web Service (/v1) & changeMessage Specification

Passinstance implements the complete Apple Wallet Web Service specification under the /v1 global route prefix:

  1. 1
    Device Registration: POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber stores the device's pushToken and links it to the pass serialNumber after verifying the ApplePass <authenticationToken> header.
  2. 2
    Silent Wakeup Push: When a notification or balance update is triggered, Apple Push Delivery sends an empty JSON payload {} over HTTP/2 to Apple's APNs gateway.
  3. 3
    Serial Polling: The iOS device wakes in the background and calls GET /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier?passesUpdatedSince=<tag>, receiving an array of updated serialNumbers and a new lastUpdated tag.
  4. 4
    Bundle Retrieval & Lock-Screen Alert: For each updated serial number, iOS requests GET /v1/passes/:passTypeIdentifier/:serialNumber (sending If-Modified-Since). iOS compares the newly downloaded pass.json against the previously stored version. Any field whose value changed and defines a changeMessage string containing the %@ placeholder triggers a lock-screen banner:
JSON
{
  "key": "points_balance",
  "label": "REWARD POINTS",
  "value": "1,450 pts",
  "changeMessage": "Your reward balance was updated to %@!"
}
  1. 5
    Device Unregistration & Error Logging: When a user deletes a pass from Apple Wallet, iOS calls DELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber. Any client-side parsing errors are reported by iOS to POST /v1/log.

Important: In Apple Wallet, changeMessage must include the %@ format specifier (which iOS replaces with the new field value), and the field's value must actually differ from its prior value on the device. Sending the exact same text value twice in a row will not trigger a second iOS lock-screen alert.

Google Wallet REST Updates & Notification Quotas

On Android, Passinstance updates the cloud pass object (LoyaltyObject, EventTicketObject, GenericObject, OfferObject, or GiftCardObject) via Google's walletobjects REST API:

  • Field Updates (PATCH): Updating points, tier labels, or text modules with notifyPreference: "NOTIFY_ON_UPDATE" prompts Google Wallet to alert the user.
  • Custom Message Objects (addMessage): Broadcast messages append a Message object (messageType: "TEXT_AND_NOTIFY") to the Google Wallet pass, subject to Google's anti-spam rate limit of maximum 3 push-notifying messages per pass within a 24-hour window.

Push Notification API Endpoints (Push Notifications API)

All push endpoints are mounted under /api/v1/push-notifications (Push Notifications API; Passes API also exposes POST /api/v1/passes/:id/notifications and POST /api/v1/passes/sendpushnotifications):

MethodEndpoint PathDTO / Payload RulesDescription
POST/api/v1/push-notifications/passes/:idrequest payload (pushNotificationText, <=85 chars; accepts pass id or externalId)Sends an immediate or optional future update to all registered devices of a single pass.
POST/api/v1/push-notifications/passes/:id/schedulerequest payload (pushNotificationText, publicationDate Y-m-d H:i, publicationTimezone?)Schedules a future notification for a single pass (id or externalId).
POST/api/v1/push-notifications/templates/:id/sendrequest payload (pushNotificationText)Broadcasts an immediate push notification update across active passes of a template (204 No Content).
POST/api/v1/push-notifications/templates/:idrequest payloadSchedules a push notification for all passes of a template (segmentIds?, savedSearchIds?).
POST/api/v1/push-notifications/segmentationrequest payload (searchId, message <=85 chars, priority?)Dispatches a targeted push notification to passes matching a saved search UUID.
POST/api/v1/push-notifications/batchrequest payload (passIds[] max 500, message, priority?)Sends an immediate push notification to up to 500 explicit pass IDs.

Example: Targeted Saved-Search Push Notification (request payload)

JSON
POST /api/v1/push-notifications/segmentation
{
  "searchId": "7b9e4c12-3f81-4a90-b8d2-19c48a70e112",
  "message": "Double points weekend starts tonight at 6 PM!",
  "priority": "HIGH"
}

Example: Single Pass Notification (externalId or UUID)

JSON
POST /api/v1/push-notifications/passes/crm_usr_44910
{
  "pushNotificationText": "Hi Marcus, you unlocked Gold Tier status!",
  "pushNotificationHeaderText": "Artisan Roasters VIP"
}

Geofencing, iBeacons & Relevant Date Triggers

In addition to server-pushed updates, passes support passive on-device lock-screen surfacing configured in the Template Editor:

  • GPS Locations (locations): Up to 10 GPS coordinates (latitude, longitude, relevantText, maxDistance) per .pkpass (and Google Wallet location arrays).
  • Bluetooth Low Energy (beacons): Up to 10 iBeacon proximity UUIDs (proximityUUID, major, minor, relevantText) for indoor retail triggers on iOS.
  • Relevant Dates (relevantDate): ISO 8601 event timestamp that automatically surfaces an Event Ticket or Boarding Pass on the lock screen as the event approaches.

Explore full delivery mechanics at Wallet Pass Notifications, Geofencing Capabilities, and Scheduled Updates & Messaging.

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.