Notifications API

Overview

The Notifications API allows you to send push notifications to digital wallet passes. There are two types of notifications:

1. Scheduled Notifications

Automatically trigger based on events, expiration dates, or location proximity. These are configured when creating or updating a pass.

2. Custom Notifications

Send immediate custom messages to one or more passes using the notifications endpoint. Perfect for promotions, updates, or time-sensitive information.

Base URL

https://app.addtowallet.co

Authentication

All API requests must include your API key in the request headers:

"apikey": "your-api-key-here"

Scheduled Notifications

Configure scheduled notifications when creating or updating passes by including these parameters:

Automatic Notification Switching

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.

Scheduled Notification Parameters

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

Event Start Notification

Notifies users 24 hours before an event starts. Requires both notificationValue and startDate.

{
  "notificationValues": ["upcomingNotification"],
  "startDate": "2025-01-15T10:00:00Z"
}

Expiry Notification

Notifies users before their pass expires. Requires both notificationValue and endDate.

{
  "notificationValues": ["expiryNotification"],
  "endDate": "2025-12-31T23:59:59Z"
}

Location-Based Notification

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." }
  ]
}

iBeacon proximity (Apple Wallet only)

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."
    }
  ]
}

Note

Include these parameters in your pass create or update API calls. See Create Pass API and Update Pass API documentation for complete examples.

Custom Notifications Endpoint

POST/api/notifications/send

This endpoint supports three operations based on the parameters provided:

1. Send to Single Pass

Send a custom notification to an individual pass immediately.

Request Parameters

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."
}

2. Send to Group (Bulk)

Send a custom notification to all passes in a user group. This operation runs in the background and processes passes in batches.

Request Parameters

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
}

Bulk Processing

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.

3. Update Notification Settings

Update the scheduled notification settings for an existing pass.

Request Parameters

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"
}

Rate Limits & Constraints

Google Wallet Limits

Google Wallet restricts notifications to 3 per pass per 24-hour period. Exceeding this limit may result in notifications being dropped.

Character Limits

• Notification heading: Maximum 100 characters
• Notification body: Maximum 500 characters

Error Codes

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

Best Practices

Keep notification messages concise and actionable
Respect the 3 notifications per pass per 24 hours limit from Google Wallet
Use scheduled notifications for time-based events to provide better user experience
Test notifications with a small group before sending to large audiences
Consider time zones when scheduling notifications for global audiences
Monitor notification delivery and engagement metrics

Notifications API

Overview

The Notifications API allows you to send push notifications to digital wallet passes. There are two types of notifications:

1. Scheduled Notifications

Automatically trigger based on events, expiration dates, or location proximity. These are configured when creating or updating a pass.

2. Custom Notifications

Send immediate custom messages to one or more passes using the notifications endpoint. Perfect for promotions, updates, or time-sensitive information.

Base URL

https://app.addtowallet.co

Authentication

All API requests must include your API key in the request headers:

"apikey": "your-api-key-here"

Scheduled Notifications

Configure scheduled notifications when creating or updating passes by including these parameters:

Automatic Notification Switching

Scheduled Notification Parameters

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

Event Start Notification

Notifies users 24 hours before an event starts. Requires both notificationValue and startDate.

{
  "notificationValues": ["upcomingNotification"],
  "startDate": "2025-01-15T10:00:00Z"
}

Expiry Notification

Notifies users before their pass expires. Requires both notificationValue and endDate.

{
  "notificationValues": ["expiryNotification"],
  "endDate": "2025-12-31T23:59:59Z"
}

Location-Based Notification

{
  "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." }
  ]
}

iBeacon proximity (Apple Wallet only)

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."
    }
  ]
}

Note

Include these parameters in your pass create or update API calls. See Create Pass API and Update Pass API documentation for complete examples.

Custom Notifications Endpoint

POST/api/notifications/send

This endpoint supports three operations based on the parameters provided:

1. Send to Single Pass

Send a custom notification to an individual pass immediately.

Request Parameters

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."
}

2. Send to Group (Bulk)

Send a custom notification to all passes in a user group. This operation runs in the background and processes passes in batches.

Request Parameters

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
}

Bulk Processing

3. Update Notification Settings

Update the scheduled notification settings for an existing pass.

Request Parameters

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"
}

Rate Limits & Constraints

Google Wallet Limits

Google Wallet restricts notifications to 3 per pass per 24-hour period. Exceeding this limit may result in notifications being dropped.

Character Limits

• Notification heading: Maximum 100 characters
• Notification body: Maximum 500 characters

Error Codes

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

Best Practices

Keep notification messages concise and actionable
Respect the 3 notifications per pass per 24 hours limit from Google Wallet
Use scheduled notifications for time-based events to provide better user experience
Test notifications with a small group before sending to large audiences
Consider time zones when scheduling notifications for global audiences
Monitor notification delivery and engagement metrics