Skip to content
Help Center Guide · Pass TemplatesOnboarding Phase 3
5 min readVerified 2026-11-16

Template Versions & Publishing

Validate completion gates, bind certificates, switch from Draft to Published, and understand live template edit behavior.

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 focus1 / 2
Key UI elements

Publishing checklist — Setup complete (Zoomed)

Verify that Signing certificate, Validation rules, and Download page all show Ready (3 of 3 completed) before issuing passes.

Overview

Passinstance implements a Single-Table Template Versioning architecture on the Template model. This allows operators to iterate on layouts, field bindings, and mechanics inside an isolated DRAFT workspace while live issued passes continue operating uninterrupted against the active PUBLISHED / PRODUCTION revision. External API issuance (POST /api/v1/passes), CSV batch imports, and public PassFlow enrollments require the template to reach PUBLISHED status.

Publishing readiness checklist
Publishing readiness checklist

System Architecture: Single-Table Versioning & Publishing Lifecycle

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
SINGLE-TABLE TEMPLATE VERSIONING & PUBLISHING
STAGE 01 Template Table (Single-Table Revision Lineage)
groupId: Shared UUID linking all revisions of the same logical template
baseId: Pointer to the canonical PRODUCTION base revision
versionNumber: Monotonically incrementing integer (v1, v2, v3...)
rowKind (TemplateRowKind): PRODUCTION | PUBLISHED | ARCHIVED | DRAFT
status (template status): DRAFT | PUBLISHED | ARCHIVED | ...
STAGE 02 PRE-PUBLISH RISK & GATE EVALUATOR
Verifies Apple Pass Type Certificate (.p12) & Google Issuer binding
Resolves all {variable} tokens against defined Custom Properties
Evaluates whether scheduled updates could overwrite critical live fields
STAGE 03 ATOMIC PROMOTION & WALLET PROPAGATION QUEUE
Template Publishing Engine
Promotes draft changes into canonical PRODUCTION / PUBLISHED lineage
Increments nextVersionNumber = (base.versionNumber ?? 0) + 1
Synchronizes relations: syncFieldsRelation, syncAttributesRelation, etc.
Preserves superseded revisions in ARCHIVED row history
If propagateUpdates: trueenqueues wallet updates for live passholders

1. Single-Table Versioning Model (Template)

Every template lineage coordinates revisions through columns and enums on the template database table (TemplateRowKind and template status: DRAFT, PUBLISHED, ARCHIVED, DEPRECATED, UNDER_REVIEW, DELETING, DELETED):

ColumnTypeDescription
groupIdUUIDImmutable lineage identifier shared across all historical snapshots and active draft/production rows.
baseId`UUID \null`References the canonical base template row (PRODUCTION / PUBLISHED) from which the revision is derived.
versionNumberintegerSequential revision counter incremented on publication (v1, v2, v3...).
rowKindTemplateRowKindPRODUCTION (canonical base row bound to passes), PUBLISHED (published snapshot), ARCHIVED (superseded historical version), or DRAFT (isolated working copy).

Draft vs. Published Architecture

When an operator opens a published template in the Visual Editor and saves a change, Passinstance does not mutate the active production row directly. Instead:

  1. 1
    It automatically forks a working draft (rowKind: DRAFT, status: DRAFT) linked by baseId and groupId.
  2. 2
    All subsequent asset uploads, field re-orderings, color adjustments, and attribute additions occur solely inside this draft row.
  3. 3
    Live issued passes on cardholders' devices continue validating against the active PRODUCTION base record.

Relations Synchronization during Publication

When a draft is promoted (Template Publishing Engine in the Passinstance API), the engine synchronizes all associated relational data inside a database transaction:

  • syncAttributesRelation & reconcilePassAttributesForTemplateInTx: Synchronizes custom property schemas and ensures existing passholder attribute records are aligned.
  • syncFieldsRelation: Atomically swaps the field collection across all layout zones (HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO, FOOTER).
  • syncMechanicsRelation: Preserves loyalty program mechanics and tiers by mapping historical mechanic IDs so issued passes maintain their earned points, stamps, or tier levels.
  • Asset, Location & Translation Sync: Copies images, geofences, iBeacons, and .strings localization dictionaries into the production record.

2. Pre-Publish Verification Gates

Before promoting a DRAFT revision, Passinstance evaluates five readiness gates:

  1. 1
    Visual Design & Required Assets: Required Apple Wallet (icon, logo) and Google Wallet (googlePayLogo) assets (image asset slot) and organization descriptions are populated.
  2. 2
    Dynamic Fields & Custom Attributes: Every {variable} token referenced in request payload maps to a declared property or system token (serialNumber, externalId, expirationDate).
  3. 3
    Mechanic & Validation Consistency: Attached pass mechanic parameters (mechanic type), cap behaviors, and custom identifier patterns (externalIdentifierPattern) are valid.
  4. 4
    Cryptographic Signing Credentials: A valid Apple Pass Type ID certificate and Google Wallet Issuer account are bound under Template Settings.
  5. 5
    Publish Risk Check (GET /api/v1/templates/:id/publish-risk-check): Detects critical field or mechanic edits and scheduled publication conflicts before propagation.

3. Does Editing a Template Update Issued Passes?

A common question for operators managing active customer card programs is how template modifications affect already-issued passes.

While Editing in Draft

No. Modifications made while working in Draft status (rowKind: DRAFT) have zero effect on issued passes. Cardholders will see no changes, and no push notifications are dispatched.

On Publish (POST /api/v1/templates/:id/publish)

When you click Publish, you configure update propagation options:

  • propagateUpdates (default: true): Determines whether the new template revision is pushed to live passes.
  • activePassesOnly (default: true): Narrows propagation to passes with status: ACTIVE, skipping voided or expired passes.
  • sendNotifications (default: true): Controls whether an audible/lockscreen notification accompanies the visual refresh.
SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
SYSTEM ARCHITECTURE FLOW
STAGE 01 WHAT UPDATES ON ISSUED PASSES:
[x] Static visual styling (background, foreground, label colors)
[x] High-resolution images (logo, strip banner, icon, thumbnail)
[x] Card layout structure (field positions, added/removed static fields)
[x] Static back-of-pass content (terms & conditions, customer support links)
[x] Geofencing locations & beacon triggers
[x] Google Wallet Class resources

The APNs Silent Push Notification Flow

For Apple Wallet passes, update propagation follows Apple's native PassKit Web Service protocol:

  1. 1
    Passinstance identifies all passes associated with the template and increments their serial update sequence.
  2. 2
    Passinstance dispatches an Apple Push Notification service (APNs) HTTP/2 silent push to each registered device token.
  3. 3
    Upon receiving the silent push, the user's iPhone contacts Passinstance's API endpoint (GET /v1/passes/:passTypeIdentifier/:serialNumber) in the background.
  4. 4
    Passinstance compiles and signs a fresh .pkpass bundle containing the updated template layout combined with the cardholder's existing personal attributes.
  5. 5
    The pass refreshes seamlessly in Apple Wallet without requiring the user to tap or re-download anything.

For Google Wallet passes, Passinstance updates the underlying Google Wallet Class resource via the Google Wallet REST API. Google's cloud infrastructure immediately mirrors the updated branding and class fields to all connected Android devices.


4. Scheduled Publication & Discarding Drafts

Schedule Future Publication

You can schedule a draft revision to publish automatically at a future calendar date and time (for example, activating holiday branding or new program rules at midnight):

POST /api/v1/templates/:id/schedule-publication Headers: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "scheduledAt": "2026-12-01 00:00",
  "timeZone": "Europe/Berlin",
  "activePassesOnly": true,
  "sendNotifications": false,
  "message": "Winter holiday branding activated."
}

If scheduledAt is set to the past or present, the server executes publication immediately.

Discard Working Draft

If you decide to abandon changes made in the Visual Editor, you can discard the uncommitted working draft and revert back to the live published state:

POST /api/v1/templates/:id/discard-draft
Headers
X-API-Key <API_KEY>
JSON
{
  "success": true,
  "description": "Template draft discarded successfully",
  "data": {
    "success": true,
    "message": "Draft discarded successfully"
  },
  "statusCode": 200
}

API Reference: Publishing Templates

Publish Draft Immediately (request payload)

POST /api/v1/templates/:id/publish Headers: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "propagateUpdates": true,
  "activePassesOnly": true,
  "sendNotifications": true,
  "notificationMessage": "New seasonal card layout is live!",
  "acknowledgePublishRiskWarning": true,
  "overrideReason": "Verified holiday strip colors on test pass"
}

HTTP Response (200 OK)

JSON
{
  "success": true,
  "description": "Template published successfully",
  "data": {
    "id": "tmpl_01hxyz987654321",
    "groupId": "grp_01hxyz987654321",
    "versionNumber": 3,
    "rowKind": "PRODUCTION",
    "status": "PUBLISHED",
    "updatedAt": "2026-11-16T21:15:00.000Z"
  },
  "statusCode": 200
}

Once your template is published, proceed to Create Individual Passes or Bulk Pass Creation.

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.