Overview: Scheduled Campaigns & Automated Messaging
Passinstance allows teams to queue time-sensitive pass updates, promotional broadcasts, CSV-driven mass notifications, and automated expiration reminders ahead of time. Scheduled jobs are persisted in database and executed by background job queue delayed worker queues, ensuring reliable fan-out across Apple APNs and Google Wallet REST endpoints at the exact target timestamp.
Scheduling Campaigns Ahead of Time
Use Batch Notifications (/batch-notifications under Batch in the Dashboard sidebar) or the REST API to queue future pass updates cleanly:
-
1
Choose Target Audience (
mode): Inrequest payload, target explicit passes (manual), saved segments/searches (filter/segment), all eligible passes (all), or upload a CSV file ofserialNumber/externalIdrecords (csvvia/api/v1/batch-notifications/csv). -
2
Author the Message: Provide
message(<=200chars in batch notifications, supporting{attributeKey}placeholders, or<=85chars inPush Notifications API). -
3
Configure Date, Time & Timezone: Supply
publicationDate(YYYY-MM-DD HH:mmor ISO 8601), resolved against the workspace's IANA timezone. While the batch stays inSCHEDULEDstatus (batch notification status:SCHEDULED,PROCESSING,SUCCESSFUL,FAILED,CANCELLED), you can update (PATCH), trigger immediately (POST /:batchId/send-now), retry (POST /:batchId/retry), or cancel (DELETE). -
4
Verify Execution & Audit Logs: Monitor progress and export per-row errors via
GET /api/v1/batch-notifications/:batchId/errors.csv.
Important: Only Installed passes with at least one active Apple Wallet device registration (
deviceLibraryIdentifier) or an active Google Wallet object can display lock-screen push notifications. Check Active Device Registrations in Analytics before scheduling.
Scheduled & Batch Notification API Endpoints
| Method | Endpoint Path | Controller | Description | ||||
|---|---|---|---|---|---|---|---|
| POST | /api/v1/push-notifications/templates/:id | Push Notifications API | Schedules a push notification (request payload) across a template (with optional segmentIds / savedSearchIds). | ||||
| POST | /api/v1/push-notifications/templates/:id/send | Push Notifications API | Immediately broadcasts a template push notification (request payload). | ||||
| POST | /api/v1/push-notifications/segmentation | Push Notifications API | Dispatches an immediate notification to a saved search (request payload). | ||||
| POST | /api/v1/batch-notifications | Batch Notifications API | Creates a scheduled batch notification (request payload: `manual \ | filter \ | csv \ | all \ | segment`). |
| GET | /api/v1/batch-notifications/:batchId | Batch Notifications API | Retrieves execution progress (SCHEDULED, PROCESSING, SUCCESSFUL, CANCELLED, FAILED) and telemetry. | ||||
| DELETE | /api/v1/batch-notifications/:batchId | Batch Notifications API | Cancels a pending SCHEDULED batch notification job before dispatch. |
Example: Scheduling a Batch Notification (request payload)
POST /api/v1/batch-notifications
{
"name": "Winter Flash Sale Push",
"message": "Hi {firstName}, enjoy 25% off today with your {memberTier} card!",
"publicationDate": "2026-11-20 17:00",
"mode": "filter",
"filters": {
"templateId": "7b9e4c12-3f81-4a90-b8d2-19c48a70e112",
"segmentIds": ["seg_vip_tier_01"]
}
}
Response (201 Created):
{
"id": "bn_8831a9c0",
"status": "SCHEDULED",
"publicationDate": "2026-11-20T16:00:00.000Z"
}
Automated Expiration & Event Countdown Reminders
In addition to manual and CSV-scheduled campaigns, you can attach automated time-based triggers under Workflows & Automation:
-
Pre-Expiration Reminders: Automatically update a warning field (e.g.,
"Your pass expires in 3 days — tap to renew")Ndays prior to a pass'sexpirationDate. -
Event Check-In Countdowns: Combine
RelevantDatelock-screen surfacing with a scheduled 24-hour pre-event push notification confirming gate, seat, or parking instructions.
Learn more in Push Notifications, Workflow Configuration, and Distribution & Engagement Analytics.
