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.

System Architecture: Single-Table Versioning & Publishing Lifecycle
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):
| Column | Type | Description | |
|---|---|---|---|
groupId | UUID | Immutable 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. |
versionNumber | integer | Sequential revision counter incremented on publication (v1, v2, v3...). | |
rowKind | TemplateRowKind | PRODUCTION (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
It automatically forks a working draft (
rowKind: DRAFT,status: DRAFT) linked bybaseIdandgroupId. -
2
All subsequent asset uploads, field re-orderings, color adjustments, and attribute additions occur solely inside this draft row.
-
3
Live issued passes on cardholders' devices continue validating against the active
PRODUCTIONbase 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
.stringslocalization dictionaries into the production record.
2. Pre-Publish Verification Gates
Before promoting a DRAFT revision, Passinstance evaluates five readiness gates:
-
1
Visual Design & Required Assets: Required Apple Wallet (
icon,logo) and Google Wallet (googlePayLogo) assets (image asset slot) and organization descriptions are populated. -
2
Dynamic Fields & Custom Attributes: Every
{variable}token referenced inrequest payloadmaps to a declared property or system token (serialNumber,externalId,expirationDate). -
3
Mechanic & Validation Consistency: Attached
pass mechanicparameters (mechanic type), cap behaviors, and custom identifier patterns (externalIdentifierPattern) are valid. -
4
Cryptographic Signing Credentials: A valid Apple Pass Type ID certificate and Google Wallet Issuer account are bound under Template Settings.
-
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 withstatus: ACTIVE, skipping voided or expired passes. -
sendNotifications(default:true): Controls whether an audible/lockscreen notification accompanies the visual refresh.
The APNs Silent Push Notification Flow
For Apple Wallet passes, update propagation follows Apple's native PassKit Web Service protocol:
-
1
Passinstance identifies all passes associated with the template and increments their serial update sequence.
-
2
Passinstance dispatches an Apple Push Notification service (APNs) HTTP/2 silent push to each registered device token.
-
3
Upon receiving the silent push, the user's iPhone contacts Passinstance's API endpoint (
GET /v1/passes/:passTypeIdentifier/:serialNumber) in the background. -
4
Passinstance compiles and signs a fresh
.pkpassbundle containing the updated template layout combined with the cardholder's existing personal attributes. -
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
{
"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:
/api/v1/templates/:id/discard-draft
{
"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
{
"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)
{
"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.
