This documentation is currently under development. Certain sections are not yet complete and will be added shortly.
Ctrlk
HomeDocumentation
For the complete documentation index, see llms.txt. This page is also available as Markdown.
GuideAPIWallet

Batch operations

Update passes in bulk using the push update API or SFTP flat file imports.

Batch operations

The Wallet Crew supports two mechanisms for updating passes in bulk: the push update API and SFTP flat file imports.

Push update API

The operation below triggers a push update on all passes that match a filter condition. This is the primary batch mechanism for API-connected systems.

The endpoint accepts the same filter array as the passes list endpoint. See Filter and query operators for the full filter reference.

Push update for passes matching the filter.

post
/api/{tenantId}/passes/pushUpdate

Authorization: Requires Pass.Write scope.

Filtering: Same as GetPasses�identifiers, metadata, pass type, installation status.

Async: Updates are queued. 200 response means scheduled, not complete. Monitor via statistics endpoint.

Data Merge: Merged into each matching pass. Set UpdateMetadata=true for recomputation (slower). Adjust Throughput for concurrency.

Bulk Operations: Ideal for campaigns, loyalty updates, seasonal offers. Use CorrelationId for tracking.

Use Cases: Campaign push; loyalty tier changes; offer refresh; bulk metadata updates.

Example — push a seasonal offer to all loyalty passes:

POST /api/{tenantId}/passes/pushUpdate
    ?filter[0].field=passType&filter[0].operator=equals&filter[0].value=loyalty
            
{
  "additionalData": { "offer": "summer2025", "discount": "20%" },
  "options": {
    "updateMetadata": true,
    "throughput": 12,
    "correlationId": "campaign-summer-2025"
  }
}
Required scopes
This endpoint requires the following scopes:
Authorizations
OAuth2implicitRequired
Authorization URL:
Path parameters
tenantIdstringRequired
Query parameters
Body
additionalDataobject · nullableOptional

Arbitrary data to persist with the pass (for example, loyalty tier, store code, or campaign flags).

passTypestring · nullableOptional

Optional pass type to convert the pass to.

updateMetadatabooleanOptionalDeprecated

Specifies if passes metadata should be updated. Updating metadata is time consuming and could be avoided for notification only push update

Default: false
Responses
200

Passes scheduled for update; returns the count in the response body.

Result returned after scheduling a bulk push update operation.

passCountinteger · int32Optional

Count of passes scheduled for update.

post/api/{tenantId}/passes/pushUpdate
200

Passes scheduled for update; returns the count in the response body.

Each matching pass is queued for update independently. The platform resolves all matching pass IDs in-request, then enqueues them as a single command containing N individual per-pass tasks. The 200 response means the batch was accepted and scheduled — not that it has completed.

There is no hard limit on the number of passes a single call can match. bypassQueue is not available on this endpoint.

You can supply a correlationId in the request body. The platform attaches it to each queued task, allowing you to track processing progress through the statistics endpoint. There is no completion webhook at the batch level.

Partial failures

Each pass is processed independently. A failure on one pass — for example, a connector error or a pass not found — does not affect the other passes in the batch. Failed passes are not retried automatically unless the underlying error is transient.

SFTP flat file imports

SFTP imports allow you to update additional data, identifiers, pass templates, and metadata across many passes by uploading a CSV file. This method is designed for legacy systems that cannot call the API directly.

SFTP imports are a last resort. Use the push update API for any system that supports HTTP calls. SFTP is an optional feature — contact The Wallet Crew to enable it on your tenant.

Each row in the CSV targets a single pass. Passes are updated asynchronously after the file is detected on the SFTP server. Like the push update API, operations are per-pass and independent.

For the full file format, column reference, SFTP credentials, and custom mapping scripts, see Update pass using flat files in the Configuration space.

Choosing between the two approaches

Push update API
SFTP flat file

Best for

Real-time or scheduled integrations with API access

Legacy systems with flat file exports only

Targeting

Filter conditions (any pass data field)

Identifier per row (explicit list)

Data updated

Triggers connector re-fetch via push

Updates additionalData, identifiers, passType, metadata directly

Setup

No extra configuration required

Optional feature — must be enabled per tenant

Progress tracking

correlationId + statistics endpoint

Fire-and-forget

Tracking batch progress in the console

The admin console provides a real-time view of all batch operations. Open Settings → Monitoring → Wallet updates.

The page shows all push update operations with the following columns:

Column
Description

Start

When the batch was queued

Last activity

Most recent processing event

Operation

Internal operation name

Correlation

The correlationId supplied in the API request

Passes

Total passes in the batch

Completed

Passes successfully processed

Errors

Passes that failed processing

Apple

Apple Wallet deliveries

Google

Google Wallet deliveries

Status

Overall batch status, such as Completed

To correlate an API call with a row, supply a correlationId in the push-update operation. The value appears in the Correlation column, making the batch easy to find among concurrent operations.

Running operations can be cancelled from this page. There is no completion webhook at the batch level. Use this view for operational monitoring.

Last updated