Pass Management
The core of The Wallet Crew API. These endpoints let you issue, read, update, and manage digital passes across Apple Wallet and Google Wallet — and record the real-world events that drive your loyalty, ticketing, and membership workflows.
The core of The Wallet Crew API. These endpoints let you issue, read, update, and manage digital passes across Apple Wallet and Google Wallet — and record the real-world events that drive your loyalty, ticketing, and membership workflows.
Pass
The Pass tag covers the full lifecycle of a wallet pass.
GET /api/{tenantId}/passes
List passes with filtering, sorting, and pagination. Requires Pass.Read.
POST /api/{tenantId}/passes
Create a new pass for a customer. Requires Pass.Write.
PATCH /api/{tenantId}/passes
Update one or more passes by internal ID or external identifiers (e.g. id.crm.customerId=…). Triggers a wallet refresh.
PATCH /api/{tenantId}/passes/{passId}
Update a single pass by its internal ID.
PUT /api/{tenantId}/passes/{passId}/notification
Send an Apple Wallet / Google Wallet push notification to a specific pass holder.
Passes are identified through external identifiers that link them to your source systems (CRM ID, loyalty number, ticket ID). Most update endpoints accept external identifiers so you never need to look up the internal passId first.
Tip — force a data refresh Set
options.UpdateMetadata = truein a PATCH body to force a full re-fetch from all configured connectors. Useoptions.BypassQueue = truefor synchronous delivery instead of the default async queue.
Benefit
A benefit is what a pass holds — a discount tier, a reward, a limited-use coupon, an entitlement. Benefits appear on the pass face and can carry a numeric value (points, balance, remaining uses) that changes over time through movements. A benefit is either created directly or granted from a benefit template configured in the back-office.
GET /api/{tenantId}/passes/{passId}/benefits
List all benefits for a pass.
GET /api/{tenantId}/passes/{passId}/benefits/{benefitId}
Retrieve a single benefit.
POST /api/{tenantId}/passes/{passId}/benefits
Create a new benefit on a pass.
PUT /api/{tenantId}/passes/{passId}/benefits/{benefitId}
Create or update (upsert) a benefit by its ID.
POST …/benefits/{benefitId}/movements
Apply a movement (issuance, redemption, adjustment) to a benefit value. Returns a movementId.
DELETE …/benefits/{benefitId}
Permanently delete a benefit.
Privilege (deprecated)
The PrivilegePass tag is the previous name of the benefit API: the same operations under /api/{tenantId}/passes/…/privileges, with the request and response shapes they have always had. It is kept for existing integrations and forwards to the benefit API. New integrations use the BenefitPass endpoints above.
Scan
The Scan tag records barcode and QR code scan events. When a pass barcode is scanned — at a POS, a venue gate, or a redemption counter — call this endpoint to:
Correlate the raw scan value to the correct pass.
Record the scan with a timestamp and symbology type.
Emit a downstream event to connected systems (Bloomreach, CRM webhooks, etc.).
data
The raw decoded barcode/QR value (3–2048 chars). Keep it stable — formatting changes break correlation.
type
Symbology: qrcode, pdf417, code128, ean13, datamatrix, nfc, or manual.
Architecture note: Call the Scan API from a backend relay rather than directly from scanning hardware. This keeps API keys server-side and allows retries, logging, and enrichment.
Authentication
All endpoints require an X-API-KEY header. API keys are tenant-scoped — a key issued for one tenant cannot access another tenant's data. Create and manage keys under Settings → API Keys & Secrets in the back-office.
Pass.Read
Reading pass data
Pass.Write
Creating, updating passes and benefits
PassScan.Scan
Recording scan events
Further reading
Getting started with the API — first API call walkthrough
Manage pass lifecycle with the API — create, update, notify, disable
Benefit guide — benefit types, sources, and movement tracking
Scan API guide — integration patterns and troubleshooting
Last updated