Overview
Once you narrow down a target pass cohort in the Dashboard using Quick Filters or the Advanced AND/OR Filter Drawer (StickySelectionToolbar), use the Bulk actions menu in the Passes toolbar—or invoke Batch Operations API (/api/v1/batch-pass-operations/*) via REST API—to execute structured array operations across up to 1,000 passes per call. Unlike multipart CSV file uploads (/api/v1/batch-processing), /api/v1/batch-pass-operations/* processes JSON payloads directly and returns per-item errors and warnings in request payload.
When updating thousands or tens of thousands of issued passes simultaneously, Passinstance decouples database mutations from mobile wallet push delivery. Changes are persisted immediately in database, while updates are broadcast to Apple Wallet devices via rate-limited, pooled HTTP/2 APNs connections and to Google Wallet devices through instant Issuer Class propagation or individual Pass Object REST patches.
System Architecture: Bulk Operations, Queue Throttling & Wallet Propagation
Filtering Target Pass Cohorts
Before executing bulk operations, administrators isolate the exact audience cohort to modify:
Quick Filters & Advanced AND/OR Filter Drawer
In the Dashboard at Passes (/passes):
-
Template Filter: Scope actions to a specific pass template or campaign card design.
-
Status Filter: Filter by lifecycle state (
ACTIVE,INACTIVE,SUSPENDED,EXPIRED,VOIDED). -
State Filter: Distinguish between
active_only(installed on at least one device),inactive_only(uninstalled), andnot_registered(unclaimed download links). -
Advanced Search Drawer (
Advanced Filter panel): Combine multiple attributes using AND/OR logic (e.g.tier == "Gold"ANDpointsBalance < 500ANDexpirationDate < 2027-01-01). -
Sticky Selection Toolbar (
StickySelectionToolbar):
- Click the master checkbox to select the current page (up to 100 passes). - Click the prompt banner to select all matching passes across all pages (e.g., "Select all 4,850 passes matching this filter").
API Cohort Selection
Via REST API, resolve target pass UUIDs using POST /api/v1/passes/query-builder or POST /api/v1/passes/search, then pass the resulting IDs into /batch-pass-operations/*.
Updating Thousands of Issued Passes
Updating large fleets of issued passes requires balancing database write throughput with the strict connection limits of mobile wallet push notification gateways.
Direct Array Operations vs. CSV Batch Ingestion
Passinstance offers two distinct pathways for bulk updates based on volume:
-
1
Direct JSON Array Operations (
POST /api/v1/batch-pass-operations/update):
- Best for up to 1,000 passes per HTTP request. - Accepts an array of passIds and a single updateData dictionary. - Synchronous HTTP response returning individual status, errors, and warnings for each pass.
-
2
Asynchronous CSV Batch Pipeline (
/api/v1/batch-processing):
- Best for 1,000 to 100,000+ passes. - Upload a CSV containing unique identifiers (externalId or serialNumber) and modified attributes. - Set operation to UPDATE_PASSES or UPSERT. - background job queue worker queues process rows asynchronously in bounded 50-row database transactions with live progress tracking and downloadable result ledgers (result.csv).
Apple Wallet APNs HTTP/2 Throttling & Connection Pooling
When updating Apple Wallet passes, Passinstance broadcasts push notifications that prompt iOS devices to wake up silently and fetch the updated .pkpass bundle from the Passinstance API:
-
Silent Push Notifications: Pass notifications are sent with
content-available: 1. They do not display intrusive lockscreen popups unless localized field change messages (e.g. "Your gate changed to B12") are configured. -
HTTP/2 Persistent Streams: The
@passinstance/apnsservice maintains pooled, persistent HTTP/2 connections to Apple's push servers (api.push.apple.com:443). Instead of tearing down and recreating TLS handshakes for each recipient, streams are multiplexed across active connections. -
Adaptive Rate Limiting & Queue Throttling:
- Outgoing notifications pass through background job queues (push-notifications, individual-push-notifications, silent-push-notifications). - Notification Rate Limiter and Notification Deduplication monitor Apple's response stream. - If APNs returns 429 TooManyRequests or connection-level backpressure, workers throttle concurrency and back off exponentially, preventing token invalidation and IP blacklisting.
Google Wallet Class Updates vs. Object PATCH
Google Wallet utilizes a hierarchical architecture separating the Pass Class (the master template definition) from the Pass Object (the individual cardholder instance):
-
Template-Level Visual & Field Updates (Issuer Class):
When a global change is published on a template (e.g. changing the header logo, background color, or program terms) and targets all cards without personalized text (!hasPersonalizedMessage), Passinstance calls Google Wallet class sync in template.service.ts. This sends a single REST PATCH to Google Wallet API to update the Issuer Class. Because every issued Google Wallet pass references this parent Class, Google's cloud servers immediately propagate the update to all active Android passes simultaneously, without generating thousands of individual API requests.
-
Passholder-Specific Attribute Updates (Pass Object):
When individual attributes differ per pass (such as individual points balances, tier upgrades, or custom names), Passinstance executes individual HTTP PATCH calls to the specific Google Wallet Pass Object (POST /batch-pass-operations/update).
Attribute Validation & Safety Rules
The batch update service (batch-pass-operations.service.ts) enforces strict data integrity:
-
Tenant Isolation: Protected fields (
customerId,tenantId,createdBy,templateId) are stripped automatically from incoming payloads. Updates cannot modify pass ownership or reassign parent templates. -
Partial Attribute Validation (
preValidateAttributes): When updating existing passes (isUpdate = true), required attribute checks are skipped. You can patch a single custom property (e.g.pointsBalance) without resending existing unchanged fields. -
Attribute Normalization: Strings are trimmed, numbers are cast to float/int, and dates are normalized to ISO-8601 UTC.
Supported Dashboard & API Bulk Operations
| Operation | API Endpoint | DTO & Behavior |
|---|---|---|
| Batch Create | POST /api/v1/batch-pass-operations/create | request payload (passes[], max 1,000 items). Issues new passes with optional externalId and bundleId. |
| Batch Update | POST /api/v1/batch-pass-operations/update | request payload (operation: "update", passIds[], updateData, optional bundleOptions). |
| Batch Upsert | POST /api/v1/batch-pass-operations/upsert | request payload (operation: "upsert", passData[]) keyed on tenant (customerId, externalId). |
| Batch Activate | POST /api/v1/batch-pass-operations/activate | request payload (operation: "activate", passIds[]) transitioning passes to ACTIVE. |
| Batch Deactivate (Void) | POST /api/v1/batch-pass-operations/deactivate | request payload (operation: "deactivate", passIds[]) transitioning passes to SUSPENDED / INACTIVE and invalidating barcodes. |
| Batch Delete | POST /api/v1/batch-pass-operations/delete | request payload (passIds[]) transitioning passes through DELETING -> soft-deleted (archivedAt: new Date()). |
| Batch Bundle | POST /api/v1/bundles/batch-create | Groups selected pass IDs into shared pass bundle containers (Pass.bundleId, up to 10 passes per bundle). |
Important: Always inspect
errorsandwarningsinrequest payload. WhenvalidateBatchOperationdetects invalid rows, the controller returnssuccess: falsewith detailed item-level error diagnostics inerrors[].
Programmatic Batch Pass Operations Reference (request payload)
1. Batch Upsert Passes (POST /api/v1/batch-pass-operations/upsert)
Ideal for CRM synchronizations or loyalty tier recalculations keyed on externalId:
HTTP Request
POST /api/v1/batch-pass-operations/upsert Headers: X-API-Key: <API_KEY> | Content-Type: application/json
{
"operation": "upsert",
"passData": [
{
"templateId": "tmpl_01hxyz987654321",
"externalId": "crm_usr_44910",
"attributes": {
"firstName": "Marcus",
"lastName": "Vance",
"pointsBalance": 1800,
"memberTier": "Platinum"
}
},
{
"templateId": "tmpl_01hxyz987654321",
"externalId": "crm_usr_44911",
"attributes": {
"firstName": "Hannah",
"lastName": "Abbott",
"pointsBalance": 250,
"memberTier": "Silver"
}
}
]
}
HTTP Response (200 OK)
{
"success": true,
"data": [
{
"id": "pass_01j8k9m2n3p4q5r6",
"externalId": "crm_usr_44910",
"serialNumber": "PI-GOLD-2026-44910",
"passAccessUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6"
},
{
"id": "pass_01j8k9m9z8y7x6w5",
"externalId": "crm_usr_44911",
"serialNumber": "PI-GOLD-2026-44911",
"passAccessUrl": "https://app.passinstance.com/p/pass_01j8k9m9z8y7x6w5"
}
],
"message": "Successfully upserted 2 passes",
"errors": [],
"warnings": []
}
2. Batch Update Passes (POST /api/v1/batch-pass-operations/update)
Patches selected passIds with shared updateData and optional bundleOptions:
POST /api/v1/batch-pass-operations/update Headers: X-API-Key: <API_KEY> | Content-Type: application/json
{
"operation": "update",
"passIds": [
"pass_01j8k9m2n3p4q5r6",
"pass_01j8k9m9z8y7x6w5"
],
"updateData": {
"expirationDate": "2028-03-31T23:59:59Z",
"attributes": {
"seasonalOffer": "2x Winter Bonus Points"
}
}
}
HTTP Response (200 OK)
{
"success": true,
"data": [
{
"id": "pass_01j8k9m2n3p4q5r6",
"status": "ACTIVE",
"updatedAt": "2026-11-16T12:00:00.000Z"
},
{
"id": "pass_01j8k9m9z8y7x6w5",
"status": "ACTIVE",
"updatedAt": "2026-11-16T12:00:00.000Z"
}
],
"message": "Successfully updated 2 passes",
"errors": [],
"warnings": []
}
3. Batch Activate, Deactivate, or Delete Passes
-
Activate:
POST /api/v1/batch-pass-operations/activate({ "operation": "activate", "passIds": [...] }) -
Deactivate:
POST /api/v1/batch-pass-operations/deactivate({ "operation": "deactivate", "passIds": [...] }) -
Delete:
POST /api/v1/batch-pass-operations/delete({ "passIds": [...] }viarequest payload)
Delivery Integration: Which Placeholder Inserts the Pass Link? ({passDownloadUrl})
Which placeholder inserts the pass link?
When following up bulk operations with automated email or SMS notifications, Passinstance provides a flexible placeholder substitution engine (pass-url-placeholder.util.ts). The canonical placeholder token is {passDownloadUrl}.
Canonical Placeholder & Supported Aliases
The official, canonical placeholder is {passDownloadUrl}. Passinstance also supports backward-compatible aliases:
| Placeholder Token | Canonical / Alias | Resolved Output Example |
|---|---|---|
{passDownloadUrl} | Canonical | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{passLink} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{smartLink} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{downloadUrl} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{passUrl} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{walletDownloadUrl} | Dynamic Alias | Context-aware link redirecting based on client OS |
Formatting Flexibility: Passinstance normalizes double-curly syntax
{{passDownloadUrl}}, snake_case{pass_download_url}, and PascalCase{PassDownloadUrl}to the canonical token automatically.
Direct Wallet Action Buttons & Conditional Flags
For responsive HTML email templates, you can construct direct single-tap wallet buttons rather than relying exclusively on the intermediate PassFlow page:
| Variable | Description |
|---|---|
{appleWalletUrl} | Direct binary .pkpass download stream triggering native Apple Wallet installation on iOS Safari. |
{googleWalletUrl} | Direct Google Wallet Add-to-Wallet deep link (https://pay.google.com/gp/v/save/...). |
{samsungWalletUrl} | Direct Samsung Wallet save deep link. |
{walletButtonText} | Context-aware button label ("Add to Apple Wallet", "Save to Google Wallet", or "Download my pass"). |
{showAppleWalletButton} | Boolean flag (true/false) indicating if Apple Wallet assets are configured. |
{showGoogleWalletButton} | Boolean flag indicating if Google Wallet integration is active. |
Partial Failures, Error Handling & Audit Logging
When invoking batch operations, requests do not fail entirely if a subset of items contains errors:
-
1
Per-Item Failure Isolation: In
updateBatchPasses, each pass is processed in an isolated try-catch block. A failure on row 42 (e.g. invalid date format) does not prevent rows 1–41 or 43–100 from succeeding. -
2
Standard Error Structure: Failed items are reported in
errors[]containingpassId,errormessage, anderrorCode:
{
"passId": "pass_01j8k9m2n3p4q5r6",
"error": "Attribute 'pointsBalance' must be a valid number",
"errorCode": "ATTR_VALIDATION"
}
-
3
Workspace Audit Logging: Every bulk operation generates an entry in
pass audit logand the workspace audit log (GET /api/v1/audit-log/export.csv) capturing the actor ID, IP address, operation type, affected count, and timestamp.
For CSV file-based batch imports, see Bulk Pass Creation. For mass voiding across an entire template, see Pass Lifecycle & Statuses.
