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

Template Design & Configuration

Master the Visual Editor: pass types, colors with WCAG contrast checking, logos, strip images, and barcode formats.

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

Brand colors & WCAG contrast (Zoomed)

Set label, value, and background colors with one-click Auto-fix contrast, Swap colors, voided colors, and Apple/Google Wallet adaptation.

Overview

A Pass Template (Template model) defines the structural geometry, visual branding, field layout zones, barcode symbology, and location-based relevancy rules shared by all passes issued under a program. Passinstance compiles a single canonical template configuration into both native Apple Wallet (.pkpass) archives and Google Wallet (Class / Object) cloud definitions.

Open any template in the Dashboard and enter Edit Template to configure design and wallet rules side by side with a live Apple Wallet and Google Wallet preview, or manage templates programmatically via /api/v1/templates.

Editor brand colors and contrast checker
Editor brand colors and contrast checker

System Architecture: Template Serialization Pipeline

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
TEMPLATE DESIGN & SERIALIZATION PIPELINE
STAGE 01 VISUAL EDITOR / REST API (/api/v1/templates)
6 Field Zones
(HeaderBack)
13 Image Slots
(@1x, @2x, @3x)
Color Schema
(RGB / Hex)
11 Barcode &
Geofencing
STAGE 02 TEMPLATE VALIDATION & COMPILER ENGINE
Enforces PassKind geometry constraints (storeCard, eventTicket, etc.)
Validates layout field count limits and square barcode constraints
Converts color tokensrgb(r, g, b) for Apple & #RRGGBB for Google
Generates retina asset derivatives (@1x, @2x, @3x) in cloud object storage
Validates WCAG 2.1 AA contrast ratios & barcode encoding (iso-8859-1/utf-8)
STAGE 03A APPLE WALLET (.pkpass Bundle)
pass.json dictionary serialization
icon.png, logo@2x.png, strip.png
locations[], beacons[], nfc{}
STAGE 03B GOOGLE WALLET (Class Resource)
LoyaltyClass / EventTicketClass
hexBackgroundColor & heroImage
callbackOptions & Smart Tap config

1. Creating a Template: The 4-Step Wizard

When creating a new template in the Dashboard (Templates -> + New Template), the Template Creation Wizard guides operators through a 4-step workflow:

  1. 1
    Step 1: Details: Enter the template name (e.g., "Artisan Coffee Club"), organizationName (rendered in the wallet header), and an accessible description. Operators can optionally import an existing .passdesign, .plist, or .pkpass archive.
  2. 2
    Step 2: Pass Type: Choose one of the 6 canonical pass kinds (PassKind: storeCard, coupon, eventTicket, boardingPass, generic, or posterGeneric).
  3. 3
    Step 3: Wallet Apps: Select target wallet ecosystems (IWalletApps: appleWalletEnabled and googlePayEnabled).
  4. 4
    Step 4: Completion & Certificate: Assign an Apple Pass Type ID signing certificate (uploadCertificate or select an existing active certificate from workspace settings).

Mandatory Icon Requirement

In accordance with Apple PassKit specifications, every template requires an icon asset (normalizeWizardImage(seedImages?.icon)). If no icon is provided or imported, the creation wizard will throw: 'Template icon is required' Passinstance provides default high-resolution seed icons for each pass kind if a custom icon is not immediately uploaded.

Initial Status Lifecycle

Newly created templates are initialized directly into status: template status.PUBLISHED (with rowKind: PRODUCTION) in the database (createTemplatePayload.ts:130). This allows immediate pass issuance and API testing. Subsequent edits in the Visual Editor spawn an isolated DRAFT row (rowKind: DRAFT), ensuring live passes remain stable until changes are explicitly published.


2. Template Editor Overview: Layout & Navigation

The Visual Editor interface consists of four primary functional areas:

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
SYSTEM ARCHITECTURE FLOW
STAGE 01 COMMAND BAR: [Draft / Live Toggle] [Version History] [Issues (0)] [Publish Btn]

The 8 Sidebar Sections (sidebarSections.ts)

  1. 1
    Pass setup: Template identity, name, organization name, pass kind selection, and Preferred Style Scheme.
  2. 2
    Design & content: Front layout field zones, Back content, Brand colors with contrast verification, Wallet images, Featured actions, and Languages & translations.
  3. 3
    Wallet actions: Value added opportunities, Actions button, Wallet links, Sharing controls (sharingProhibited), and Linked app banners (associatedStoreIdentifiers).
  4. 4
    Validation & access: Primary barcode symbology, Watch fallback barcodes, dynamic security animation, and manual entry alternative text.
  5. 5
    Engagement & messaging: Welcome notification, Expiry & validity rules, Relevant dates, Location geofencing, and iBeacon proximity triggers.
  6. 6
    Program rules: Loyalty program mechanic assignment (e.g., Points & Tiers, Stamp Card, Cashback).
  7. 7
    Integrations & automation: Custom attributes schema definition and Apple Semantic Tags.
  8. 8
    Template settings: Guided tour (PassTour), external identifier validation regex, and certificate bindings.

Pass-Specific Tabs: When configuring a boardingPass, the sidebar dynamically exposes an Airline & Transit Services tab (transitType, flight numbers, airport codes). When configuring an eventTicket, it exposes an Event Guide tab (venue maps, upcoming events, and companion URLs).

The CommandBar

The top floating CommandBar provides:

  • Draft vs. Live Toggle: Switch between viewing the active published card and the working draft in the simulator.
  • Platform Switcher: Toggle the simulator between Apple Wallet and Google Wallet.
  • Autosave & Issues Drawer: Displays real-time schema validation errors (such as contrast warnings or missing fields).
  • Publish Button: Launches the publication modal to promote drafts to live passes.

3. Pass Kinds & Layout Limits (maxFieldsConfig.ts)

Each pass kind serves distinct operational use cases and enforces strict field limits governed by Apple PassKit geometry rules:

Pass Kind (PassKind)Primary Use CaseHeader FieldsPrimary FieldsSecondary FieldsAuxiliary FieldsBack FieldsAdditional Info
storeCardRetail loyalty, gift cards, prepaid cardsMax 3Max 1Max 4Max 4UnlimitedMax 50
couponDiscounts, vouchers, promotional offersMax 3Max 1Max 30 (Forbidden)UnlimitedMax 50
eventTicketConcerts, sports matches, conferencesMax 3Max 1Max 4Max 4UnlimitedMax 50
boardingPassFlights, trains, buses, ferriesMax 3Max 2 (Dep/Arr)Max 4Max 5UnlimitedMax 50
genericMembership IDs, gym passes, access badgesMax 3Max 1Max 4Max 4UnlimitedMax 50
posterGenericHigh-impact modern digital badgesMax 1Max 40Max 2 (Footer)UnlimitedMax 50

The Square Barcode Invariant

Important: On generic, coupon, and storeCard templates, if a square 2D barcode format is selected (PKBarcodeFormatQR or PKBarcodeFormatAztec), Apple PassKit limits the total combined number of Secondary + Auxiliary fields to a maximum of 4. Exceeding 4 combined fields causes Apple Wallet to truncate or hide the lower field row.

Back Fields & Additional Info Fields

  • Back Fields (BACK): Rendered on the reverse side of Apple Wallet passes (tapped via the (i) or ... menu). They support long multiline text, clickable web links (<a href="...">), phone numbers (tel:), email addresses (mailto:), and automated data detectors (dataDetectorTypes).
  • Additional Info Fields (ADDITIONALINFO): Introduced in iOS 18+ for event tickets and boarding passes to render companion venue details, parking instructions, entry gate guidelines, and event schedules below the primary pass fold.

4. Image Sizes Reference & Retina Variants {#image-sizes-reference}

Passinstance manages 13 distinct image asset slots. When you upload a high-resolution source image, the asset pipeline automatically downscales and packages @1x, @2x, and @3x retina variants for Apple Wallet while hosting public CDN URLs required by Google Wallet:

Asset Slot KeyTarget Platform@1x Dimensions@2x Dimensions@3x DimensionsAspect Ratio / File RulesPurpose & Layout Placement
iconApple Wallet38 x 38 px76 x 76 px114 x 114 px1:1 square, PNGMandatory. Push notifications & lock-screen icon
logoApple Wallet160 x 50 px320 x 100 px480 x 150 pxMax canvas, PNGTop-left brand mark next to logoText
primaryLogoUnified / Fallback160 x 50 px320 x 100 px480 x 150 pxMax canvas, PNGCanonical brand mark inherited across wallet targets
stripApple (storeCard, coupon)375 x 123 px750 x 246 px1125 x 369 px~3.05:1 ratio, PNGFull-bleed horizontal banner behind/above primary fields
strip (eventTicket)Apple (eventTicket < iOS 18)375 x 98 px750 x 196 px1125 x 294 px~3.83:1 ratio, PNGHorizontal hero image for event passes
backgroundApple (eventTicket, generic)180 x 220 px360 x 440 px540 x 660 px~0.82:1 ratio, PNGFull-card blurred background texture
thumbnailApple (generic, membership)90 x 90 px180 x 180 px270 x 270 px1:1 (or 2:3 to 3:2), PNGSquare portrait photo ID or product badge on card right
footerApple (boardingPass)286 x 15 px572 x 30 px858 x 45 pxWide strip, PNGNarrow banner printed immediately above barcode
artworkApple Poster Event Ticket358 x 448 px716 x 896 px1074 x 1344 px~0.80:1 ratio, PNGHigh-impact full poster artwork (top 984px visible)
venueMapApple iOS 18 Event Guide375 x 375 px750 x 750 px1125 x 1125 px1:1 square, PNGSeating chart or venue floor plan in Event Guide
secondaryLogoUnified Co-Branding160 x 50 px320 x 100 px480 x 150 pxMax canvas, PNGSecondary partner or sponsor logo
googlePayLogoGoogle Wallet660 x 660 px——1:1 circular maskProgram logo in Google Wallet header (center 70% safe)
androidBackgroundGoogle Wallet1032 x 336 px——~3.07:1 heroGoogle Wallet hero banner override (heroImage)
androidCardBackgroundGoogle Wallet1080 x 1320 px——~0.82:1 full cardFull card background image override
googlePayWideLogoGoogle Wallet1280 x 400 px——16:5 ratio, transparentWide rectangular header logo option

File & Asset Invariants

  • Format: All uploaded assets must be in PNG format (transparency supported). Lossy JPG files are automatically rejected or converted to PNG.
  • Maximum File Size: 5 MB (5242880 bytes) per image file.
  • Google Wallet Circular Mask: Google Wallet applies a circular mask to googlePayLogo. Ensure brand graphics and text remain inside the center 70% safe zone.

5. Colors & WCAG AA Contrast Checking

The Color model persists four semantic color properties:

  • backgroundColor: Main card body background.
  • foregroundColor: Value text, member name, and primary numbers.
  • labelColor: Field captions, section headers, and metadata labels.
  • stripColor: Accent tint applied to strip image overlays.

Platform Serialization Rules

  • Apple Wallet (rgb(r, g, b)): Apple's pass.json parser strictly mandates CSS RGB format (rgb(24, 24, 27)) and rejects hexadecimal strings (#18181B) or alpha channels (rgba). Passinstance automatically serializes RGB triplets when building .pkpass bundles.
  • Google Wallet (#RRGGBB): Google Wallet API resources mandate 6-character hexadecimal color strings.
  • WCAG 2.1 AA Contrast Validation: The Visual Editor automatically calculates the luminance contrast ratio between backgroundColor and foregroundColor / labelColor. If the contrast drops below the 4.5:1 ratio required for standard text, an inline warning is displayed in the issues drawer to prevent unreadable passes.

6. Supported Barcode Symbologies & Watch Fallbacks

Passinstance supports 11 barcode formats across retail, transit, and contactless ticketing:

Barcode Format (barcode format)Symbology TypeNative Apple WalletNative Google WalletTypical Use Case
PKBarcodeFormatQR2D Matrix (Square)YesYes (QR_CODE)Loyalty cards, smart PassFlow pages, camera scanners
PKBarcodeFormatPDF4172D Stacked LinearYesYes (PDF_417)Airline boarding passes, transit tickets, state IDs
PKBarcodeFormatAztec2D Matrix (Square)YesYes (AZTEC)Rail tickets, European transit, high-density tickets
PKBarcodeFormatCode1281D LinearYesYes (CODE_128)POS retail laser scanners, inventory member cards
PKBarcodeFormatCode391D LinearFallback RequiredYes (CODE_39)Industrial badges, automotive, legacy systems
PKBarcodeFormatCodabar1D LinearFallback RequiredYes (CODABAR)Libraries, blood banks, logistics parcels
PKBarcodeFormatEAN131D LinearFallback RequiredYes (EAN_13)Retail products, grocery coupons, UPC checkouts
PKBarcodeFormatI2of51D InterleavedFallback RequiredYes (ITF / ITF_14)Warehouse distribution, shipping cartons
PKBarcodeFormatNoneNone (Contactless)No barcodeNo barcodeNFC-only passes (nfcNoBarcode: true)

Apple Watch Fallback Barcode Requirement

Because 1D linear barcodes (such as Code 128 or EAN-13) cannot be rendered legibly on small watchOS displays, Apple PassKit mandates a 2D fallback barcode (QR, PDF417, or Aztec). When you select a 1D format in Passinstance, the editor prompts you to assign an Apple Watch Fallback Format (defaults to PKBarcodeFormatQR).

Security Animation & Encodings

  • Security Animation (addSecurityAnimation: true): Renders a dynamic, iridescent anti-screenshot shimmer across the barcode on iOS, proving the pass is active in Apple Wallet rather than a static screenshot.
  • Character Encodings (messageEncoding): Supported encodings include iso-8859-1 (Apple default), UTF-8, ISO-8859-15, Windows-1252, and Shift_JIS.

7. Validity, Locations & Relevant Dates

GPS Geofencing (Location Model)

Attach up to 10 GPS coordinates per template. When a passholder approaches within range, iOS and Android automatically present the pass on the lock screen:

  • latitude: -90.0 to 90.0.
  • longitude: -180.0 to 180.0.
  • altitude: Optional altitude in meters.
  • maxDistance: Search radius in meters (min 100m, max 10,000m, default 1,000m).
  • relevantText: Custom lockscreen message (e.g., "Welcome to Artisan Roasters! Tap to scan your card.").

Bluetooth Low Energy iBeacons (Beacon Model)

Attach up to 10 iBeacons for fine-grained indoor proximity triggers at store entrances, cash registers, or event gates:

  • proximityUUID: 128-bit UUID string.
  • major / minor: 16-bit integer sub-identifiers (0 to 65535).
  • relevantText: Lockscreen notification message displayed when entering beacon range.

Relevant Dates (RelevantDates.tsx)

Configure up to 10 date intervals (startDate, endDate, or point-in-time date) to surface passes on the lock screen when an event or flight is imminent.

Expiration Strategies

  • none: The pass remains valid indefinitely.
  • fixed: All passes expire at a fixed calendar date/time (expirationDate).
  • duration: Dynamic expiration where expirationDate = issuanceDate + validityInDays.

8. Advanced Features & Functionalities

  • Sharing Prevention (sharingProhibited: true): Disables the Apple Wallet share sheet, AirDrop forwarding, and pass exports on iOS.
  • App Store Linkage (associatedStoreIdentifiers): Provide numeric iTunes App Store identifiers (e.g., [123456789]) to display an "Install App" or "Open App" banner on the back of the pass.
  • NFC Contactless (Apple VAS & Google Smart Tap): Configure contactless tap-to-present payloads (message, encryptionPublicKey, requiresAuthentication with Face ID / Touch ID, and nfcNoBarcode). Requires an active Apple VAS Certificate (type: TYPE_NFC).
  • Welcome Notifications (welcomeNotification): Dispatches a push greeting to the lock screen immediately after the passholder installs the pass.

9. Troubleshooting & Frequently Asked Questions

My template preview does not update after editing

If edits made in the Visual Editor are not visible in the simulator:

  1. 1
    Check Preview Source Mode: In the top CommandBar, verify that the simulator toggle is set to Draft rather than Live. Live mode displays the canonical published base version, which does not reflect uncommitted draft edits.
  2. 2
    Platform Switcher: Check whether you are viewing the Apple Wallet tab while modifying Google Wallet fields (or vice versa).
  3. 3
    Conditional Visibility Mock Data: If a field has a showWhen condition (e.g., {tier} == "VIP"), the simulator hides the field if the mock attributes do not satisfy the condition. Open simulator settings to populate matching test data.
  4. 4
    Form Debounce: Complex color and layout inputs are debounced by 300ms. Click outside the input field or inspect the CommandBar autosave indicator.

My logo looks blurry on the download page

  • Root Cause: The public download page (PassDownload.tsx) renders brand logos inside a container styled with max-w-44 h-10 (up to 176 CSS pt width). On modern Retina displays (@2x and @3x), this container requires 352 to 528 physical pixels for sharp rendering. Uploading a standard 1x logo (160x50 px) forces the browser to upscale the raster image over 300%, causing visible blurriness.
  • Solution: Upload high-resolution assets at @3x resolution (PNG at least 480x150 px, or 660x660 px for square logos) in both Template Images (logo) and Company Settings / Workspace Branding. Ensure the PNG is tightly cropped without unnecessary transparent borders.

How do I show the expiration date on the pass?

Apple Wallet uses metadata expirationDate for pass lifecycle management, but does not automatically print the date on the front card face. To display the expiration date visibly to passholders:

  1. 1
    Navigate to Design & content -> Front layout (or Back content).
  2. 2
    Click + Add field in Secondary or Auxiliary fields.
  3. 3
    Set the Field Label to EXPIRES (or localized text).
  4. 4
    Set the Field Value to {expirationDate} (or dynamic attribute {expiresAt}).
  5. 5
    In field properties, select a Date Style:

- PKDateStyleShort (e.g., 12/31/26) - PKDateStyleMedium (e.g., Dec 31, 2026) - PKDateStyleLong (e.g., December 31, 2026)

  1. 6
    Check ignoresTimeZone: true if the expiration date is universal across time zones.

API Reference: Template Operations

Create Template (request payload)

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

JSON
{
  "name": "Artisan Coffee Club - Gold",
  "kind": "storeCard",
  "organizationName": "Artisan Roasters GmbH",
  "description": "Artisan Coffee Loyalty Card",
  "colors": {
    "backgroundColor": "rgb(20, 35, 28)",
    "foregroundColor": "rgb(255, 255, 255)",
    "labelColor": "rgb(167, 243, 208)",
    "stripColor": "rgb(255, 255, 255)"
  },
  "barcode": {
    "format": "PKBarcodeFormatQR",
    "messageEncoding": "UTF_8",
    "altText": "{cardNumber}",
    "addSecurityAnimation": true
  },
  "locations": [
    {
      "latitude": 52.520008,
      "longitude": 13.404954,
      "maxDistance": 150,
      "relevantText": "Welcome back to Artisan Roasters! Tap to scan your card."
    }
  ]
}

HTTP Response (201 Created)

JSON
{
  "success": true,
  "data": {
    "id": "tmpl_01hxyz987654321",
    "groupId": "grp_01hxyz987654321",
    "versionNumber": 1,
    "rowKind": "PRODUCTION",
    "status": "PUBLISHED",
    "name": "Artisan Coffee Club - Gold",
    "kind": "storeCard",
    "createdAt": "2026-11-16T20:50:00.000Z"
  },
  "statusCode": 201
}

Continue to Dynamic Fields & Personalization to bind custom properties to your layout, or learn about Template Versions & Publishing.

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.