Skip to content
Help Center Guide · Projects & Organization
5 min readVerified 2026-11-16

Manage Projects

Group a Primary Pass Template with Linked Templates into Wallet Experiences, bundles, and segment-driven switching.

In This Guide

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

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
PASS PROJECT BUNDLING (.PKPASSES) & SEGMENT AUTOMATION
STAGE 01 PASS PROJECT (PassProject & PassProjectTemplate)
PRIMARY (mainTemplateId): Anchor Membership / Ticket / Flight Boarding Pass
LINKED / VIP / CUSTOM: Companion Lounge Voucher / Parking / Gala Card
PRIVACY_MODE / INACTIVE: Stripped privacy layout or paused companion card
STAGE 02A APPLE PASS BUNDLE (.pkpasses ZIP)
Bundles up to 10 signed .pkpass files matching shared Pass.bundleId
MIME: application/vnd.apple.pkpasses
iOS displays "Add All" dialog
bundle grouping mode: AUTO | `MANUA
STAGE 02B SEGMENT & AUTOMATION ORCHESTRATOR
Evaluates PassProjectSegment rules against Pass.attributes (GIN)
Triggers AutomationFlow actions: issue linked pass / switch template `

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 .pkpass files (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.

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):

PassProjectTemplateRoleWhere StoredFunctional Responsibility in the Project
PRIMARYPassProject.mainTemplateIdThe anchor identity pass (e.g., Season Ticket, Hotel Room Key, or Loyalty Card) whose externalId and customer attributes govern the experience.
LINKED / VIP / CUSTOMPassProjectTemplate.roleCompanion templates (e.g., VIP Backstage Access, Drink Coupon, Parking Pass) bundled on download or issued dynamically via segment/automation rules.
PRIVACY_MODEPassProjectTemplate.roleAn alternative stripped-down template switched in automatically when a passholder opts out of tracking/personalization.
INACTIVEPassProjectTemplate.roleLinked template temporarily suppressed from new bundle downloads without unlinking history.

3. Step-by-Step: Configuring a Multi-Template Bundle in the Dashboard

  1. 1
    Navigate to Wallet Experiences (/wallet-experiences) in the Dashboard and click + New Project.
  2. 2
    Name your experience (e.g., "Summer Festival VIP Weekend") and set the URL slug.
  3. 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).

  1. 4
    In the Distribution tab:

- Toggle Bundle on Download to ON. - Set Max Bundle Size (from 2 up to 10 passes).

  1. 5
    When passes are issued via PassFlow or API, Passinstance generates the consolidated .pkpasses archive automatically.

Important: Apple iOS enforces an upper limit of 10 .pkpass files inside a single .pkpasses archive (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. 1
    Dynamic Segment Evaluation: Define filter rules over Pass.attributes (e.g., attributes.spendTotal >= 500) and evaluate via POST /api/v1/pass-projects/:id/segments/:segmentId/evaluate.
  2. 2
    Automated Companion Issuance: When a primary pass enters a segment, an attached AutomationFlow automatically issues a linked companion pass (LINKED / VIP) and shares its updated bundle/download link.
  3. 3
    Privacy Mode Switching: If personalization consent is disabled, the experience can migrate the holder's pass to the PRIVACY_MODE template.

Pass Projects REST API Reference (Projects API)

All project endpoints are mounted under /api/v1/pass-projects (alias /api/v1/wallet-experiences):

HTTP Method & EndpointDescription
GET /api/v1/pass-projectsLists all Wallet Experiences (Pass Projects) in the active workspace.
POST /api/v1/pass-projectsCreates a new PassProject with request payload (name, mainTemplateId, bundleOnDownload, maxBundleSize, slug).
GET /api/v1/pass-projects/:idRetrieves project configuration, linked templates, readiness, and segments.
PATCH /api/v1/pass-projects/:idUpdates project name, description, mainTemplateId, bundleOnDownload, maxBundleSize, or slug.
POST /api/v1/pass-projects/:id/templates/:templateIdLinks a companion template (LINKED, VIP, PRIVACY_MODE, CUSTOM, INACTIVE).
GET / PATCH /api/v1/pass-projects/:id/bundleConfigures bundle ordering, limits (maxBundleSize), and .pkpasses metadata.
POST /api/v1/pass-projects/:id/download-bundleDownloads/generates the coordinated .pkpasses bundle archive for a pass/issuance.
GET /api/v1/pass-projects/bundle-passes/:passIdLists 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

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)

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

Related Product & Developer Documentation

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.