Overview
As your organization scales across seasonal campaigns, regional store branches, and staging vs. production environments, Passinstance provides multi-layered workspace organization tools: Template Categorization & Tagging, Template Cloning (Template Duplication Wizard), rowKind Lifecycle Filtering (DRAFT, PUBLISHED, PRODUCTION, ARCHIVED), Composite External ID Uniqueness Enforcement, database GIN-Indexed Attribute Search (attribute search index), and Cross-Project Template Mapping.
System Architecture: Workspace Taxonomy, Cloning & Saved Views
1. Copying a Template: Copy an Existing Template (Template Cloning & Duplication)
Rather than reconfiguring colors, field layouts, barcodes, and custom property schemas from scratch for each new card program, you can duplicate any existing template in seconds.
How to Clone in the Dashboard
Operators can initiate template cloning from two locations:
-
1
From Templates Directory: On any template card, click the Three Dots (...) menu and select Duplicate.
-
2
From the Visual Editor: In the top CommandBar, click Actions -> Duplicate Template.
The 4-Step Template Duplication Wizard Workflow
The Template Duplication Wizard guides operators through duplicating a template:
-
1
Step 1: Select Source Template: Confirms the source template and inspects its pass kind, field count, and attached images.
-
2
Step 2: Name & Description: Pre-populates the new template name with
${sourceTemplate.name} (Copy)and allows entering a distinct description. -
3
Step 3: Customization:
- Linked PassFlow Registration Page: Choose whether to clone the associated public registration form via duplicatePassFlow (creating an independent /f/:newUrl PassFlow page) or leave the new template without an attached form. - Brand Colors: Modify backgroundColor, foregroundColor, and labelColor. The wizard executes real-time WCAG AA contrast validation to ensure legibility. - Visual Assets: Choose whether to retain the source template's images (icon, logo, strip, thumbnail) or upload new brand assets.
-
4
Step 4: Certificate Assignment: Select an existing Apple Pass Type ID signing certificate from workspace settings or upload a new
.p12/.cercertificate.
2. Workspace Isolation & Template Naming Hygiene
Passinstance isolates templates, passes, certificates, and API keys at the Customer workspace boundary inside your parent Organization (POST /api/v1/organizations/current/workspaces):
-
1
Separate Environments by Workspace: Keep experimental drafts and integration tests in a
sandboxworkspace, reserving yourproductionworkspace exclusively for live customer programs. -
2
Standardize Template Names & Tags: Include program domain, region, and version in template titles (for example,
Loyalty-CoffeeClub-EU-v2) and attach structuredtags(e.g.,["retail", "q4-2026", "dach"]) for instant catalog filtering. -
3
Archive Superseded Templates (
rowKind: ARCHIVED): Instead of deleting historical promotional templates that still have issued pass records attached, transition them to Archived. Archived templates are hidden from default active pickers while preserving historical analytics and scan logs under the All / Archived filter.
3. External ID Uniqueness, Custom Identifiers & Bundle Grouping
To prevent issuing duplicate passes across web forms, POS terminals, and CRM webhooks, configure identifier and bundling policies in Template Settings:
| Setting / Model Property | Database & API Enforcement | |
|---|---|---|
externalId (Pass.externalId) | Caller-supplied string (max 255 chars) uniquely indexed per live non-deleted tenant pass (@@unique([customerId, externalId]) WHERE archivedAt IS NULL). Duplicate POST /api/v1/passes calls reject, while POST /api/v1/passes/upsert-by-external-id updates in place. | |
Custom Identifier Rules (Template) | Configure customIdentifiersEnabled, externalIdentifierPattern, and customIdentifierValidationPattern in Template Settings to enforce organization-wide regex formats on generated/imported external identifiers. | |
Multi-Card Grouping (Pass.bundleId) | Foreign key bundleId linking up to 10 passes into one pass bundle (bundle grouping mode: AUTO \ | MANUAL) for .pkpasses delivery. |
Single Device Binding (limitToOneActivePerPass) | Restricts smart download links so a single pass cannot be shared and installed concurrently across unauthorized devices. |
Important: Enforcing
externalIduniqueness is strongly recommended for loyalty, membership, and prepaid gift card templates. Soft-deleting a test pass (SOFTdelete) setsarchivedAtand immediately frees thatexternalIdfor reuse.
4. structured JSON Attribute Indexing (attribute search index) & Saved Views
Every custom property stored inside Pass.attributes is automatically indexed by database's Generalized Inverted Index (attribute search index). This allows operators and API consumers to organize and query millions of passes without schema migrations:
-
Operator Saved Views: In the Passes directory (
/passes), combine AND/OR filter predicates acrossstatus(pass status),lifecycleStatus,walletVoidStatus(WalletPropagationStatus),bundleId,externalId, device platform (APPLE_WALLETvs.GOOGLE_WALLET), and custom structured JSON keys (attributes.tier,attributes.storeId), then save the query as a Saved View. -
Cross-Project Template Mapping: Group related templates into Wallet Experiences (
PassProject) rather than cloning standalone templates. A single template can act as aLINKED,VIP,CUSTOM, orPRIVACY_MODEtemplate acrossPassProjectcontainers (PassProjectTemplateRole) while maintaining centralized asset and mechanic governance.
API Reference: Template Duplication & Filtering
1. Duplicate a Template via API (POST /api/v1/templates/:id/duplicate)
Clones an existing template, copying its layout fields, colors, barcodes, and custom property definitions:
POST /api/v1/templates/tmpl_01hxyz987654321/duplicate Headers: X-API-Key: <API_KEY> | Content-Type: application/json
{
"name": "Artisan Coffee Club - Platinum Tier (Copy)",
"duplicatePassFlow": true,
"certificateId": "cert_01j7k8m9n2p3"
}
HTTP Response (201 Created)
{
"success": true,
"data": {
"id": "tmpl_new_clone_01h987",
"name": "Artisan Coffee Club - Platinum Tier (Copy)",
"kind": "storeCard",
"status": "PUBLISHED",
"versionNumber": 1,
"rowKind": "PRODUCTION",
"createdAt": "2026-11-16T21:20:00.000Z"
},
"statusCode": 201
}
2. Filter Templates by Status, Kind & Tags
/api/v1/templates?rowKind=PRODUCTION&kind=storeCard&tag=retail&search=Coffee&page=1&limit=20
{
"success": true,
"data": {
"items": [
{
"id": "tmpl_01hxyz987654321",
"groupId": "grp_01hxyz987654321",
"name": "Loyalty-CoffeeClub-EU-v2",
"kind": "storeCard",
"rowKind": "PRODUCTION",
"status": "PUBLISHED",
"versionNumber": 2,
"tags": ["retail", "q4-2026", "dach"],
"activePassesCount": 14820
}
],
"total": 1,
"page": 1,
"limit": 20
},
"statusCode": 200
}
Explore Manage Projects to merge passes from several templates, or read Understand Your Workspace for multi-workspace tenancy rules.
