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.
Apple Wallet Web Service (/v1) & changeMessage Specification
Passinstance implements the complete Apple Wallet Web Service specification under the /v1 global route prefix:
-
1
Device Registration:
POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumberstores the device'spushTokenand links it to the passserialNumberafter verifying theApplePass <authenticationToken>header. -
2
Silent Wakeup Push: When a notification or balance update is triggered,
Apple Push Deliverysends an empty JSON payload{}over HTTP/2 to Apple's APNs gateway. -
3
Serial Polling: The iOS device wakes in the background and calls
GET /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier?passesUpdatedSince=<tag>, receiving an array of updatedserialNumbersand a newlastUpdatedtag. -
4
Bundle Retrieval & Lock-Screen Alert: For each updated serial number, iOS requests
GET /v1/passes/:passTypeIdentifier/:serialNumber(sendingIf-Modified-Since). iOS compares the newly downloadedpass.jsonagainst the previously stored version. Any field whosevaluechanged and defines achangeMessagestring containing the%@placeholder triggers a lock-screen banner:
{
"key": "points_balance",
"label": "REWARD POINTS",
"value": "1,450 pts",
"changeMessage": "Your reward balance was updated to %@!"
}
-
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 toPOST /v1/log.
Important: In Apple Wallet,
changeMessagemust include the%@format specifier (which iOS replaces with the new fieldvalue), and the field'svaluemust 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 withnotifyPreference: "NOTIFY_ON_UPDATE"prompts Google Wallet to alert the user. -
Custom Message Objects (
addMessage): Broadcast messages append aMessageobject (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):
| Method | Endpoint Path | DTO / Payload Rules | Description |
|---|---|---|---|
| POST | /api/v1/push-notifications/passes/:id | request 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/schedule | request 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/send | request payload (pushNotificationText) | Broadcasts an immediate push notification update across active passes of a template (204 No Content). |
| POST | /api/v1/push-notifications/templates/:id | request payload | Schedules a push notification for all passes of a template (segmentIds?, savedSearchIds?). |
| POST | /api/v1/push-notifications/segmentation | request payload (searchId, message <=85 chars, priority?) | Dispatches a targeted push notification to passes matching a saved search UUID. |
| POST | /api/v1/push-notifications/batch | request 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)
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)
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.
