Overview
In the Passinstance Dashboard, multi-pass Projects (PassProject model managed by Projects API at /api/v1/pass-projects and alias /api/v1/wallet-experiences) appear in the Wallet Experiences hub (/wallet-experiences, organizing workspace tabs Overview, Cards, Audience, Automations, Distribution, Analytics, and Settings).
A Project coordinates a primary mainTemplateId plus linked companion templates into unified customer journeys, supporting Apple Wallet Pass Bundles (.pkpasses) (Pass.bundleId / pass bundle) and rule-based segment automation. This architecture makes it effortless to merge passes from several templates into a single, cohesive delivery flow.
System Architecture: Pass Projects, .pkpasses Bundling & Segment Triggers
1. Merging Passes from Several Templates (Wallet Experiences & Bundles)
When hosting an event, managing a resort stay, or offering an airline itinerary, customers frequently require multiple related passes:
-
An Event Ticket (Primary Pass)
-
A VIP Backstage Pass or Lounge Access Voucher (Companion Pass)
-
A Parking Permit (Companion Pass)
Instead of forcing recipients to open three separate links or scan three separate QR codes, Passinstance merges passes generated from distinct templates into a Pass Bundle.
The Apple Wallet Pass Bundle (.pkpasses)
-
Format: A ZIP archive with MIME type
application/vnd.apple.pkpasses. -
Capacity: Contains up to 10 digitally signed
.pkpassfiles (maxBundleSize <= 10). -
Shared Grouping: All companion passes share the same
Pass.bundleId(bundleId). -
iOS "Add All" Prompt: When the customer opens the bundle link on iPhone or iPad, iOS MobileSafari and Wallet open a carousel previewing all cards simultaneously with a prominent Add All button in the top right corner. The customer adds all passes to Apple Wallet with a single tap.
The Google Wallet Multi-Pass Claim Link
For Android users, Passinstance generates a coordinated multi-pass save URL (GET /api/v1/bundles/:id/google-wallet-link). Clicking the link opens Google Wallet and adds all issued pass objects in a single batch.
2. Core Models & Template Roles (PassProjectTemplateRole)
Each PassProject binds a mainTemplateId (PRIMARY role on the project itself) alongside linked companion templates (PassProjectTemplate, writable roles LINKED, PRIVACY_MODE, VIP, CUSTOM, INACTIVE):
PassProjectTemplateRole | Where Stored | Functional Responsibility in the Project |
|---|---|---|
PRIMARY | PassProject.mainTemplateId | The anchor identity pass (e.g., Season Ticket, Hotel Room Key, or Loyalty Card) whose externalId and customer attributes govern the experience. |
LINKED / VIP / CUSTOM | PassProjectTemplate.role | Companion templates (e.g., VIP Backstage Access, Drink Coupon, Parking Pass) bundled on download or issued dynamically via segment/automation rules. |
PRIVACY_MODE | PassProjectTemplate.role | An alternative stripped-down template switched in automatically when a passholder opts out of tracking/personalization. |
INACTIVE | PassProjectTemplate.role | Linked template temporarily suppressed from new bundle downloads without unlinking history. |
3. Step-by-Step: Configuring a Multi-Template Bundle in the Dashboard
-
1
Navigate to Wallet Experiences (
/wallet-experiences) in the Dashboard and click + New Project. -
2
Name your experience (e.g.,
"Summer Festival VIP Weekend") and set the URL slug. -
3
In the Cards tab:
- Select your Primary Template (e.g., Festival General Admission Ticket). - Click + Add Companion Card to link secondary templates (e.g., VIP Camping Pass, Beverage Voucher).
-
4
In the Distribution tab:
- Toggle Bundle on Download to ON. - Set Max Bundle Size (from 2 up to 10 passes).
-
5
When passes are issued via PassFlow or API, Passinstance generates the consolidated
.pkpassesarchive automatically.
Important: Apple iOS enforces an upper limit of 10
.pkpassfiles inside a single.pkpassesarchive (maxBundleSize <= 10). Every template included in a bundle must be published with a valid Apple Pass Type ID certificate.
4. Audience Segments (PassProjectSegment) & Automations
Projects integrate directly with PassProjectSegment and AutomationFlow to orchestrate dynamic multi-pass journeys without external webhook glue code:
-
1
Dynamic Segment Evaluation: Define filter rules over
Pass.attributes(e.g.,attributes.spendTotal >= 500) and evaluate viaPOST /api/v1/pass-projects/:id/segments/:segmentId/evaluate. -
2
Automated Companion Issuance: When a primary pass enters a segment, an attached
AutomationFlowautomatically issues a linked companion pass (LINKED/VIP) and shares its updated bundle/download link. -
3
Privacy Mode Switching: If personalization consent is disabled, the experience can migrate the holder's pass to the
PRIVACY_MODEtemplate.
Pass Projects REST API Reference (Projects API)
All project endpoints are mounted under /api/v1/pass-projects (alias /api/v1/wallet-experiences):
| HTTP Method & Endpoint | Description |
|---|---|
GET /api/v1/pass-projects | Lists all Wallet Experiences (Pass Projects) in the active workspace. |
POST /api/v1/pass-projects | Creates a new PassProject with request payload (name, mainTemplateId, bundleOnDownload, maxBundleSize, slug). |
GET /api/v1/pass-projects/:id | Retrieves project configuration, linked templates, readiness, and segments. |
PATCH /api/v1/pass-projects/:id | Updates project name, description, mainTemplateId, bundleOnDownload, maxBundleSize, or slug. |
POST /api/v1/pass-projects/:id/templates/:templateId | Links a companion template (LINKED, VIP, PRIVACY_MODE, CUSTOM, INACTIVE). |
GET / PATCH /api/v1/pass-projects/:id/bundle | Configures bundle ordering, limits (maxBundleSize), and .pkpasses metadata. |
POST /api/v1/pass-projects/:id/download-bundle | Downloads/generates the coordinated .pkpasses bundle archive for a pass/issuance. |
GET /api/v1/pass-projects/bundle-passes/:passId | Lists all companion passes grouped with a specific passId via bundleId. |
Example: Create a Multi-Pass Project (request payload)
POST /api/v1/pass-projects Headers: X-API-Key: <API_KEY> | Content-Type: application/json
{
"name": "Alpine Ski Resort - VIP Winter Package",
"description": "Season ski pass with aprés-ski voucher and parking permit",
"mainTemplateId": "tmpl_ski_season_pass_01",
"bundleOnDownload": true,
"maxBundleSize": 3,
"slug": "alpine-vip-winter-2026"
}
HTTP Response (201 Created)
{
"success": true,
"data": {
"id": "proj_01j9k8l7m6n5p4",
"name": "Alpine Ski Resort - VIP Winter Package",
"slug": "alpine-vip-winter-2026",
"mainTemplateId": "tmpl_ski_season_pass_01",
"bundleOnDownload": true,
"maxBundleSize": 3,
"createdAt": "2026-11-16T21:25:00.000Z"
},
"statusCode": 201
}
See Pass Bundling Architecture for technical packaging flows and Organize Templates & Passes to manage template catalogs.
