Skip to content
Help Center Guide · Projects & OrganizationOnboarding Phase 3
4 min readVerified 2026-11-16

Organize Templates & Passes

Keep template catalogs clean using naming standards, Archive filters, external ID uniqueness policies, and saved views.

In This Guide

Interactive UI Walkthroughs

Open in 6-Phase Onboarding Guide

Inspect exact dashboard panels, controls, and zoomed callouts related to this guide.

Zoomed UI focus
Key UI elements

Template Settings — Signing & External IDs (Zoomed)

Review Signing certificate status, Wallet sort order, Published template state, and External ID uniqueness rules in the Settings tab.

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

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
WORKSPACE TAXONOMY, CLONING & SAVED VIEWS
STAGE 01 ORGANIZATION (Organization Model)
+-- Production Workspace (Customer: kind = 'production')
+-- Sandbox Workspace (Customer: kind = 'sandbox')
STAGE 02 TEMPLATE CATALOG & PROJECT CLUSTERS (Template / PassProject)
Filter by rowKind: PUBLISHED | PRODUCTION | DRAFT | ARCHIVED
Categorization: Program tags[], passType, and PassProjectTemplate links
Cloning Engine: POST/api/v1/templates/:id/duplicate (Template Duplication Wizard)
External ID Policy: Unique constraint on (customerId, externalId)
STAGE 03 HIGH-SPEED PASS DIRECTORY & SAVED VIEWS (Pass Table)
B-Tree Indexes: (customerId, templateId, status, serialNumber, externalId)
structured JSON high-speed search index (attribute search index): Instant custom attribute queries
Saved Views: Persisted AND/OR filter trees per operator or workspace

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. 1
    From Templates Directory: On any template card, click the Three Dots (...) menu and select Duplicate.
  2. 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. 1
    Step 1: Select Source Template: Confirms the source template and inspects its pass kind, field count, and attached images.
  2. 2
    Step 2: Name & Description: Pre-populates the new template name with ${sourceTemplate.name} (Copy) and allows entering a distinct description.
  3. 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.

  1. 4
    Step 4: Certificate Assignment: Select an existing Apple Pass Type ID signing certificate from workspace settings or upload a new .p12 / .cer certificate.

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. 1
    Separate Environments by Workspace: Keep experimental drafts and integration tests in a sandbox workspace, reserving your production workspace exclusively for live customer programs.
  2. 2
    Standardize Template Names & Tags: Include program domain, region, and version in template titles (for example, Loyalty-CoffeeClub-EU-v2) and attach structured tags (e.g., ["retail", "q4-2026", "dach"]) for instant catalog filtering.
  3. 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 PropertyDatabase & 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 externalId uniqueness is strongly recommended for loyalty, membership, and prepaid gift card templates. Soft-deleting a test pass (SOFT delete) sets archivedAt and immediately frees that externalId for 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 across status (pass status), lifecycleStatus, walletVoidStatus (WalletPropagationStatus), bundleId, externalId, device platform (APPLE_WALLET vs. 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 a LINKED, VIP, CUSTOM, or PRIVACY_MODE template across PassProject containers (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

JSON
{
  "name": "Artisan Coffee Club - Platinum Tier (Copy)",
  "duplicatePassFlow": true,
  "certificateId": "cert_01j7k8m9n2p3"
}

HTTP Response (201 Created)

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

GET /api/v1/templates?rowKind=PRODUCTION&kind=storeCard&tag=retail&search=Coffee&page=1&limit=20
Headers
X-API-Key <API_KEY>
JSON
{
  "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.

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.