Skip to content
Help Center Guide · Pass ManagementOnboarding Phase 5
8 min readVerified 2026-11-16

Bulk Operations

Execute Bulk Actions on filtered pass cohorts — mass field updates, batch voiding, bulk deletion, and targeted exports.

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

Passes tab & Bulk actions toolbar (Zoomed)

After importing passes in bulk, use the Passes tab, filters, and 'Bulk actions' menu to inspect or update generated cards.

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

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
BULK PASS OPERATIONS & WALLET PROPAGATION
STAGE 01 DASHBOARD BULK TOOLBAR / API (Batch Operations API)
Cohort Selection (StickySelectionToolbar / Filter Drawer / Pass IDs)
POST/api/v1/batch-pass-operations/update (operation: "update")
POST/api/v1/batch-pass-operations/upsert (Keyed on externalId)
POST/api/v1/batch-pass-operations/activate (operation: "activate")
POST/api/v1/batch-pass-operations/deactivate (operation: "deactivate")
POST/api/v1/batch-pass-operations/delete (request payload)
POST/api/v1/batch-pass-operations/validate (Pre-flight payload check)
STAGE 02 ISOLATED PER-ITEM VALIDATION & EXECUTION ENGINE
Strips tenant-protected keys (customerId, tenantId, createdBy)
Pre-validates attributes via preValidateAttributes (skips required on update)
Normalizes attributes via normalizeAttributes
Returns request payload: { success, data, message, errors, warnings }
STAGE 03A APNs HTTP/2 THROTTLED WORKER QUEUE
background job queue: `push-notificatio
Persistent HTTP/2 connection pooling
Rate-limiting avoids Apple 429 errors
Silent push wakes device to pull pass
STAGE 03B GOOGLE WALLET CLASS PROPAGATION
s` | | - Template change: PATCH Issuer Cl
Instant sync to ALL Android passes
Individual Pass Object PATCH for pass-specific dynamic attributes

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), and not_registered (unclaimed download links).
  • Advanced Search Drawer (Advanced Filter panel): Combine multiple attributes using AND/OR logic (e.g. tier == "Gold" AND pointsBalance < 500 AND expirationDate < 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. 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.

  1. 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/apns service 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

OperationAPI EndpointDTO & Behavior
Batch CreatePOST /api/v1/batch-pass-operations/createrequest payload (passes[], max 1,000 items). Issues new passes with optional externalId and bundleId.
Batch UpdatePOST /api/v1/batch-pass-operations/updaterequest payload (operation: "update", passIds[], updateData, optional bundleOptions).
Batch UpsertPOST /api/v1/batch-pass-operations/upsertrequest payload (operation: "upsert", passData[]) keyed on tenant (customerId, externalId).
Batch ActivatePOST /api/v1/batch-pass-operations/activaterequest payload (operation: "activate", passIds[]) transitioning passes to ACTIVE.
Batch Deactivate (Void)POST /api/v1/batch-pass-operations/deactivaterequest payload (operation: "deactivate", passIds[]) transitioning passes to SUSPENDED / INACTIVE and invalidating barcodes.
Batch DeletePOST /api/v1/batch-pass-operations/deleterequest payload (passIds[]) transitioning passes through DELETING -> soft-deleted (archivedAt: new Date()).
Batch BundlePOST /api/v1/bundles/batch-createGroups selected pass IDs into shared pass bundle containers (Pass.bundleId, up to 10 passes per bundle).

Important: Always inspect errors and warnings in request payload. When validateBatchOperation detects invalid rows, the controller returns success: false with detailed item-level error diagnostics in errors[].


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

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)

JSON
{
  "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

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)

JSON
{
  "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": [...] } via request payload)

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 TokenCanonical / AliasResolved Output Example
{passDownloadUrl}Canonicalhttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{passLink}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{smartLink}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{downloadUrl}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{passUrl}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{walletDownloadUrl}Dynamic AliasContext-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:

VariableDescription
{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. 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. 2
    Standard Error Structure: Failed items are reported in errors[] containing passId, error message, and errorCode:
JSON
{
     "passId": "pass_01j8k9m2n3p4q5r6",
     "error": "Attribute 'pointsBalance' must be a valid number",
     "errorCode": "ATTR_VALIDATION"
   }
  1. 3
    Workspace Audit Logging: Every bulk operation generates an entry in pass audit log and 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.

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.