Skip to content
Help Center Guide · Introduction to PassinstanceOnboarding Phase 2
5 min readVerified 2026-11-16

Key Concepts & Terminology

Clear definitions of Templates, Passes, Mechanics, Attributes, Wallet Experiences (Projects), PassFlow, and Active Registrations.

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

Custom properties & attributes (Zoomed)

Define reusable customer attributes ({serviceOrDuration}, {holderName}, {passReference}, {validUntil}, {memberQrToken}) and configure data types and validation flags.

Core Platform Architecture & Entities

To build reliable wallet workflows, developers and administrators must understand how Passinstance organizes templates, dynamic pass records, business logic mechanics, and device registration states.

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
ENTITY RELATIONSHIPS
STAGE 01 Template (Blueprint & Versioning)
Layout: StoreCard, EventTicket, Coupon, Membership
Colors, Barcode Symbology, Field Mapping, Asset Slots
STAGE 02 1:N Issuance | 1:1 Rule Attachment
Pass (Concrete Instance)
SerialNumber & AuthToken
Dynamic Field Values
Status & ExpirationDate
1:N Device Registration (Apple A
pass mechanic (State Engine)
Type: STAMP_CARD_ADD, LOYALTY_PROGRAM, PREPAID_CARD,
VALID_ONCE_PER_DAY
Saves)

Backend Entity Schema & platform resource Mapping

Each platform concept directly corresponds to a structured platform resource within the Passinstance API database layer:

Conceptplatform resourceResponsibilities & Stored Attributes
TemplateTemplateStores visual configuration, layout kind (pass type), asset relations (image asset slot), barcode rules, custom identifier regexes, and single-table versioning (groupId, versionNumber, rowKind: `PRODUCTION \PUBLISHED \ARCHIVED \DRAFT, status`: template status).
PassPassRepresents an individual issued card. Holds id, unique serialNumber, authenticationToken, downloadCode, optional tenant-unique externalId, optional bundleId (bundleId), optional idempotencyKey, structured JSON attributes, expirationDate, artifact readiness (appleArtifactStatus, googleArtifactStatus), and lifecycle/void flags.
Pass Mechanicpass mechanicConfigures stateful rules attached to a template. Stores mechanicType (mechanic type), minimumValue, maximumValue, defaultChangeValue, tiers (PassTier), and cap handling rules.
Prepaid Accountprepaid accountManages stored monetary value for gift and prepaid cards. Tracks integer balance units and links to immutable prepaid ledger entry transaction logs.
Pass Bundlepass bundleGroups up to 10 companion passes via Pass.bundleId (bundle grouping mode: `AUTO \MANUAL, BundleStatus: ACTIVE \CANCELLED) to download multi-card .pkpasses` archives.
Wallet ExperiencePassProjectOrchestrates a primary template (mainTemplateId) and linked templates (PassProjectTemplateRole: `PRIMARY \LINKED \PRIVACY_MODE \INACTIVE \VIP \CUSTOM`), unified claim pages, bundles, segments, and visual automation flows.
PassFlowPassFlowManages multi-step self-service intake pages (/f/:url, PassFlowType, PassFlowStatus) with customizable forms, SMS/Email OTP verification, bot protection (SpamProtectionMode), payment gateways, and direct wallet handoffs.
Scanner ConfigurationScannerConfigurationConfigures physical check-in locations (ValidationPlace), scoped ScannerKey tokens, validation modes (ScanMode), NFC reader settings (NfcReaderMode), and offline dataset sync.

Core Pass Identifiers & Correlation Keys

When integrating CRMs, e-commerce checkouts, or ticketing backends, understand the exact role of each identifier on a Pass:

FieldPassinstance database Column / ScopeMutability & FormatPrimary Purpose
idUUID primary keySystem-generated, immutableInternal API resource reference (GET /api/v1/passes/:id).
serialNumberGlobally unique stringSystem-generated (or custom when configured), immutableCanonical Apple Wallet .pkpass identifier and Google object suffix.
externalId@unique([customerId, externalId]) where archivedAt IS NULLCaller-supplied string (max 255 chars)Business key from your CRM, POS, or ticketing DB enabling idempotent POST /api/v1/passes/upsert-by-external-id and lookup via GET /api/v1/passes/by-external-id/:externalId.
bundleIdbundleId (UUID foreign key to pass bundle)System-managed via /api/v1/bundles/* or PassProjectGroups up to 10 passes into a multi-card .pkpasses Apple bundle or unified claim experience.
idempotencyKey@unique([customerId, idempotencyKey])Supplied via Idempotency-Key header (<=128 chars [A-Za-z0-9._:-]+)Prevents duplicate pass issuance if an HTTP POST /api/v1/passes request is retried; verified via SHA-256 request body hash.
downloadCode / authenticationTokenPer-pass security tokensSystem-generated cryptographic stringsPublic short download code and Apple Web Service Authorization: ApplePass <token> shared secret.

State Machine Enums & Lifecycle Mapping

Pass records transition through strict state machines across Passinstance database enums during creation, wallet sync, and voiding/deletion:

Pass Status (pass status)

  • DRAFT: Provisioned as an unissued draft and not yet available for public installation.
  • AWAITING_OPT_IN: Generated during opt-in/OTP registration flows; awaiting verification before activation.
  • GENERATING: Undergoing asynchronous pass or artifact generation.
  • ACTIVE: Issued and valid. Available for wallet installation and scanner validation.
  • INACTIVE: Temporarily paused/deactivated; scanners reject validation until reactivated.
  • EXPIRED: Passed its expirationDate; scanners reject with reason PASS_EXPIRED.
  • REDEEMED: Single-use coupon or voucher that has completed redemption.
  • CANCELLED, SUSPENDED, PENDING_ACTIVATION: Specialized billing, administrative, and pre-activation states.
  • VOIDED: Revoked or voided by an administrator or scan rule; scanners reject with PASS_VOIDED.

Pass Lifecycle, Deletion Mode & Artifact Readiness

  • PassLifecycleStatus: Controls irreversible voiding and purge transitions:
TEXT
ACTIVE  --->  VOIDING  --->  VOIDED  --->  DELETING  --->  DELETED
  • PassDeletionMode: Distinguishes soft deletion (SOFT, preserves audit history and frees externalId uniqueness for live passes) vs. permanent removal (HARD, DELETE /api/v1/passes/:id/hard).
  • ArtifactStatus (appleArtifactStatus & googleArtifactStatus): Tracks per-ecosystem generation health (NOT_GENERATED, GENERATING, READY, FAILED, INVALIDATED).

Wallet Void & Propagation Status (walletVoidStatus / WalletPropagationStatus)

Tracks asynchronous propagation of void/update state to Apple APNs and Google Wallet on the Pass.walletVoidStatus field:

  • NONE: No propagation pending.
  • PENDING: State recorded in database; awaiting queue enqueue.
  • QUEUED: Dispatched to background job queue wallet sync workers.
  • SUCCEEDED: Apple APNs wake-up or Google REST PATCH acknowledged.
  • FAILED: Downstream wallet push failed (eligible for automated retry or manual regeneration).

Custom Properties & Dynamic Token Interpolation

Passinstance uses dynamic bracket syntax {propertyName} to bind customer data into card fields:

  • Syntax: Place {firstName}, {pointsBalance}, or {membershipTier} in any primary, secondary, auxiliary, or back field label or value.
  • Change Messages: Configure changeMessage: "You earned a stamp! You now have %@ stamps." on Apple Wallet fields. When updated, the %@ token is replaced with the new value, generating an immediate iOS lock-screen notification banner.
  • Attributed Values: Apple Wallet back fields support HTML anchor tags (<a href="https://example.com">Terms</a>) for clickable web links, phone numbers, and email addresses.

Important: Billing capacity meters Active Wallet Passes (the total number of devices currently registered via Apple APNs or Google Wallet objects), rather than unissued draft records or expired passes.

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.