Google Sheet Extension
PDF to Pass
Image to Pass
The Notifications API allows you to send push notifications to digital wallet passes. There are two types of notifications:
Automatically trigger based on events, expiration dates, or location proximity. These are configured when creating or updating a pass.
Send immediate custom messages to one or more passes using the notifications endpoint. Perfect for promotions, updates, or time-sensitive information.
All API requests must include your API key in the request headers:
"apikey": "your-api-key-here"
Configure scheduled notifications when creating or updating passes by including these parameters:
When both upcomingNotification and expiryNotification are provided, the system automatically sets upcomingNotification first, then switches toexpiryNotification 24 hours after the start date. This ensures users get both notifications without manual intervention.
| Name | Type | Required | Description |
|---|---|---|---|
| notificationValues | array<string> | string | No | One or more scheduled notifications to enable. When both upcomingNotification and expiryNotification are provided, upcomingNotification is set first and automatically switches to expiryNotification 24 hours after the start date. For backward compatibility, a single string is also accepted. Allowed values: `upcomingNotification`, `expiryNotification`, `locationNotification`, `beaconNotification` (Apple Wallet only for proximity; requires `appleBeacons` or `beacons` array with valid rows). |
| appleBeacons | array<Beacon> | No | Apple Wallet only: up to 10 iBeacon rows when `beaconNotification` is enabled (alias field name `beacons` accepted on create/update cleanup). PKPass emits `proximityUUID`, `major`, `minor`, and optional `relevantText`. |
| proximityUUID | string | Yes | iBeacon proximity UUID |
| major | number | Yes | 0–65535 |
| minor | number | Yes | 0–65535 |
| relevantText | string | No | Optional lock-screen message when user is near this beacon |
| startDate | string (ISO 8601) | Conditional | Event start date. Required when notificationValues includes upcomingNotification. |
| endDate | string (ISO 8601) | Conditional | Pass expiry date. Required when notificationValues includes expiryNotification. |
| locations | array<Location> | Location | No | Merchant locations to trigger proximity notifications (up to 10). A single object is accepted for backward compatibility. Optional message per location for Apple Wallet custom lock-screen text. |
| latitude | number | Yes | Latitude in range -90 to 90 |
| longitude | number | Yes | Longitude in range -180 to 180 |
| message | string | No | Apple only: custom text shown when user is near this location |
| altitude | number | No | Optional altitude in meters |
Notifies users 24 hours before an event starts. Requires both notificationValue and startDate.
{
"notificationValues": ["upcomingNotification"],
"startDate": "2025-01-15T10:00:00Z"
}Notifies users before their pass expires. Requires both notificationValue and endDate.
{
"notificationValues": ["expiryNotification"],
"endDate": "2025-12-31T23:59:59Z"
}Notifies users when they are near a specific location. Requires notificationValues including locationNotification and locations array. Use optional message per location for Apple Wallet custom lock-screen text.
{
"notificationValues": ["upcomingNotification", "expiryNotification", "locationNotification"],
"startDate": "2025-01-15T10:00:00Z",
"endDate": "2025-01-16T10:00:00Z",
"locations": [
{ "latitude": 37.7749, "longitude": -122.4194 },
{ "latitude": 37.331, "longitude": -122.029, "message": "Store nearby on 3rd and Main." }
]
}Include beaconNotification and an appleBeacons array (alias beacons). Google Wallet scheduled notifications do not use beacon proximity; PKPass includes a root beacons array.
{
"notificationValues": ["beaconNotification"],
"appleBeacons": [
{
"proximityUUID": "E2C56DB5-DFFB-48D2-B060-D0F5A71096E0",
"major": 1,
"minor": 2,
"relevantText": "Welcome — you're at the entrance."
}
]
}Include these parameters in your pass create or update API calls. See Create Pass API and Update Pass API documentation for complete examples.
This endpoint supports three operations based on the parameters provided:
Send a custom notification to an individual pass immediately.
| Name | Type | Required | Description |
|---|---|---|---|
| passId | string | Yes | Unique ID of the pass to notify |
| heading | string | Yes | Notification title (max 100 characters) |
| body | string | Yes | Notification message (max 500 characters) |
{
"passId": "66b6005bb7bddce8f05a3392",
"heading": "Special Offer!",
"body": "Your exclusive discount is now active. Show this pass at checkout."
}Send a custom notification to all passes in a user group. This operation runs in the background and processes passes in batches.
| Name | Type | Required | Description |
|---|---|---|---|
| groupId | string | Yes | Unique ID of the user group |
| heading | string | Yes | Notification title (max 100 characters) |
| body | string | Yes | Notification message (max 500 characters) |
| bulkSend | boolean | No | If true, triggers background bulk processing. Default: `true` |
{
"groupId": "66b6005bb7bddce8f05a3393",
"heading": "Important Update",
"body": "We've updated your membership benefits. Check your pass for details.",
"bulkSend": true
}Group notifications are processed asynchronously in batches of 100 passes. The API returns immediately while notifications are sent in the background. This ensures optimal performance even for large groups.
Update the scheduled notification settings for an existing pass.
| Name | Type | Required | Description |
|---|---|---|---|
| passId | string | Yes | Unique ID of the pass to update |
| notificationValue | string | Yes | Type of scheduled notification. Allowed values: `upcomingNotification`, `expiryNotification`, `locationNotification`, `beaconNotification` (Apple only; requires valid `appleBeacons` when used) |
| startDate | string (ISO 8601) | Conditional | Required for upcomingNotification |
| endDate | string (ISO 8601) | Conditional | Required for expiryNotification |
| location | object | Conditional | Required for locationNotification |
| latitude | number | Yes | Latitude -90 to 90 |
| longitude | number | Yes | Longitude -180 to 180 |
{
"passId": "66b6005bb7bddce8f05a3392",
"notificationValues": [
"upcomingNotification",
"expiryNotification"
],
"startDate": "2025-01-15T10:00:00Z",
"endDate": "2025-01-16T10:00:00Z"
}Google Wallet restricts notifications to 3 per pass per 24-hour period. Exceeding this limit may result in notifications being dropped.
The API may return the following error codes:
| Status Code | Error | Description |
|---|---|---|
| 400 | Bad Request | Missing required fields, invalid notification type, or validation errors |
| 401 | Unauthorized | Missing or invalid API key |
| 403 | Forbidden | You do not have permission to send notifications for this pass or group |
| 404 | Not Found | Pass or group with the specified ID does not exist |
| 429 | Too Many Requests | API rate limit exceeded. Try again later |
| 500 | Internal Server Error | Unexpected server error. Please contact support |