Skip to content
Help Center Guide · Wallet Updates & NotificationsOnboarding Phase 6
3 min readVerified 2026-11-16

Scheduled Updates & Messaging

Schedule batch notification campaigns, segment audiences ahead of events or expirations, and audit execution logs.

In This Guide

Interactive UI Walkthroughs

Open in 6-Phase Onboarding Guide

Inspect exact dashboard panels, controls, and zoomed callouts related to this guide.

Zoomed UI focus
Key UI elements

Template Activity log — Updates & push notifications (Zoomed)

Verify that template version publications and push notifications execute cleanly across all active Apple Wallet and Google Wallet passes.

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.

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
SCHEDULED & BATCH NOTIFICATION ENGINE
STAGE 01 CAMPAIGN SCHEDULING & INGESTION
Scheduled Template Push (POST/api/v1/push-notifications/templates/:id)
Saved-Search Campaign (POST/api/v1/push-notifications/segmentation)
Batch / CSV Notification (POST/api/v1/batch-notifications & /csv)
Automated Lifecycle Cron (Expiration Reminders & Tier Renewal Alerts)
STAGE 02 TIMEZONE RESOLUTION & ASYNC DELAYED QUEUE
1
Resolve target execution time via resolveCustomerTimeZone (IANA Timezone)
2
Persist batch (batch notification status: SCHEDULED)
3
Enqueue background job queue delayed job (delay = scheduledAt - now())
At publicationDate Timestamp
STAGE 03 WORKER FAN-OUT & WALLET PROPAGATION PIPELINE
1
Query eligible ACTIVE passes with active APNs / Google Wallet registrations
2
Mutate designated notification field value & increment pass revision
3
Dispatch APNs HTTP/2 silent pushes & Google Wallet walletobjects patches
4
Record per-pass results (SUCCESSFUL, FAILED, CANCELLED status)

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. 1
    Choose Target Audience (mode): In request payload, target explicit passes (manual), saved segments/searches (filter / segment), all eligible passes (all), or upload a CSV file of serialNumber / externalId records (csv via /api/v1/batch-notifications/csv).
  2. 2
    Author the Message: Provide message (<=200 chars in batch notifications, supporting {attributeKey} placeholders, or <=85 chars in Push Notifications API).
  3. 3
    Configure Date, Time & Timezone: Supply publicationDate (YYYY-MM-DD HH:mm or ISO 8601), resolved against the workspace's IANA timezone. While the batch stays in SCHEDULED status (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. 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

MethodEndpoint PathControllerDescription
POST/api/v1/push-notifications/templates/:idPush Notifications APISchedules a push notification (request payload) across a template (with optional segmentIds / savedSearchIds).
POST/api/v1/push-notifications/templates/:id/sendPush Notifications APIImmediately broadcasts a template push notification (request payload).
POST/api/v1/push-notifications/segmentationPush Notifications APIDispatches an immediate notification to a saved search (request payload).
POST/api/v1/batch-notificationsBatch Notifications APICreates a scheduled batch notification (request payload: `manual \filter \csv \all \segment`).
GET/api/v1/batch-notifications/:batchIdBatch Notifications APIRetrieves execution progress (SCHEDULED, PROCESSING, SUCCESSFUL, CANCELLED, FAILED) and telemetry.
DELETE/api/v1/batch-notifications/:batchIdBatch Notifications APICancels a pending SCHEDULED batch notification job before dispatch.

Example: Scheduling a Batch Notification (request payload)

JSON
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):

JSON
{
  "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") N days prior to a pass's expirationDate.
  • Event Check-In Countdowns: Combine RelevantDate lock-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.

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.