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

Dynamic Fields & Personalization

Bind Custom Properties and system tokens using {variableName} autocomplete across Apple and Google Wallet zones.

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

Dynamic variable autocomplete (Zoomed)

Type '{' in any field Value input to search and insert custom attributes ({passStatus}) or system pass fields ({storedValue}, {userProvidedId}, {lastUsage}).

Overview

Personalizing wallet passes for thousands or millions of cardholders relies on Custom Properties (schema definitions declared on your template) paired with {variable} bindings inside the Field model across header, primary, secondary, auxiliary, back, and footer zones. At pass generation and update time, Passinstance hydrates these tokens from the pass record's structured JSON attributes dictionary and formats dates, numbers, currencies, and lock-screen push notifications natively for Apple Wallet and Google Wallet.

Typing curly brace triggers variable autocomplete
Typing curly brace triggers variable autocomplete

System Architecture: Dynamic Field Hydration & Indexing

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
DYNAMIC FIELD HYDRATION & WALLET SERIALIZATION
STAGE 01 PASS RECORD (Pass Model in database)
serialNumber: "PI-884920-AB"
attributes (structured JSON indexed via GIN attribute search index): { "firstName": "Sophia", "pointsBalance": 1250, "tier": "Platinum" }
STAGE 02 FIELD HYDRATION & FORMATTING ENGINE
Resolves {firstName}, {pointsBalance}, {serialNumber}, {expirationDate}
Evaluates showWhen visibility conditions ({field}, ==, !=, >, <, |=, now())
Applies numberStyle, currencyCode (ISO 4217), dateStyle, timeStyle
Sanitizes attributedValue (permits <a href="..."> on Apple back fields)
Injects changeMessage with %@ token for iOS lock-screen push alerts
STAGE 03A APPLE WALLET (pass.json)
"secondaryFields": [{ "key": "points_field", "label": "POINTS BALANCE", "value": 1250, "numberStyle": "PKNumberStyleDecimal" "changeMessage": "New balance: %@"
}]
STAGE 03B GOOGLE WALLET (WalletObject)
"loyaltyPoints": { "label": "POINTS BALANCE", "balance": { "int": 1250 }
},
"textModulesData": [...]

1. Custom Attributes & Property Types (types/attributes.ts)

Before binding dynamic tokens into pass fields, define your program's data schema under Integrations & automation -> Custom attributes in the Visual Editor.

Passinstance supports 11 distinct attribute data types (PropertyType in types/attributes.ts):

Property Type (PropertyType)Description & Input RenderingSupported Validations & Formats
textSingle-line string (e.g. member name, tier code).Regex pattern, min/max length, uniqueness.
emailCustomer email address.RFC 5322 syntax validation, uniqueness.
phoneInternational telephone number.E.164 phone formatting (+14155552671), SMS OTP verification.
numberNumeric integer or decimal value (e.g. points balance, stamps).Min/max bounds, step increments, decimal formatting.
dateCalendar date (e.g. date of birth, membership expiry).ISO 8601 (YYYY-MM-DD), date style formatting.
checkboxBoolean flag (e.g. marketing consent, VIP status).Evaluates as true or false.
selectSingle-choice selection from configured options.Predefined option list with value/label pairs.
dropdownSearchable dropdown selector for large option lists.Predefined option list with autocomplete.
radioRadio button group for explicit option selection.Predefined option list.
textareaMultiline text for notes or terms.Useful for back fields and customer messages.
rangeSlider range control for numerical boundaries.Min/max bounds, default step value.

Property Schema Flags & Modifiers

Each custom attribute supports the following schema configuration flags:

  • name: The unique property key (e.g., loyaltyTier, pointsBalance). Used in variable tokens as {loyaltyTier}.
  • required: If enabled, passes cannot be issued without this attribute populated.
  • hidden: Internal property for API operations and automation; hidden from public PassFlow registration forms.
  • readonly: Passholders cannot edit this value after initial issuance.
  • isUnique: Enforces composite uniqueness across the workspace, preventing multiple active passes with the same attribute value (e.g., customer account number).
  • otp: Enables One-Time Passcode verification (SMS for phone or email code for email) during PassFlow self-enrollment.
  • validations.pattern: Optional custom regular expression (e.g. ^[A-Z]{2}-[0-9]{5}$) enforced at API and form boundaries.

2. Dynamic Variable Syntax & Autocomplete

Inside any field label, value, barcode text, or notification message, type the open curly brace { to trigger the autocomplete suggestion menu:

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
SYSTEM ARCHITECTURE FLOW
STAGE 01 Field Value: {

You can combine static text with multiple tokens in a single field:

  • Example: "Hello {firstName}, your {memberTier} status is active."
  • Example: "ID: {externalId} | Points: {pointsBalance}"

3. Conditional Field Visibility (showWhen)

Passinstance includes a powerful conditional visibility engine that dynamically shows or hides fields on the pass based on attribute values, system status, or time.

The condition evaluator (evaluatePreviewVisibilityCondition.ts in the dashboard and evaluateVisibilityCondition in the backend API) evaluates boolean expressions before rendering Apple Wallet fields and Google Wallet text modules:

Supported Syntax & Operators

OperationSyntax ExampleEvaluation Behavior
Existence / Truthiness{companionPassId}Evaluates to true if {companionPassId} is present, non-null, and non-empty.
Equality{memberTier} == "Gold"Evaluates to true when attribute exactly matches the string.
Inequality{status} != "Suspended" or {status} <> "Suspended"Evaluates to true when attribute does not match.
Numeric Greater Than{pointsBalance} > 500Parses numeric attribute and evaluates if greater than 500.
Numeric Greater or Equal{pointsBalance} >= 1000Evaluates if greater than or equal to 1000.
Numeric Less Than{strikes} < 3Evaluates if less than 3.
**List Inclusion (`\=`)**`{tier} \= Silver,Gold,Platinum`Evaluates to true if {tier} equals any of the comma-separated values.
Operating System{operatingSystem} == iOSTargets Apple Wallet (iOS / watchOS) or Google Wallet (Android).
Temporal (now())now() > 2026-12-31T23:59:59ZEvaluates pass rendering relative to current UTC timestamp.
Boolean AND (&&){tier} == "VIP" && {pointsBalance} >= 500Both conditions must be satisfied.
**Boolean OR (`\\`)**`{isVip} == true \\{spendTotal} > 1000`Either condition must be satisfied.

Feature In-Depth: Show a Field Only When Another Field Is Set

A frequent requirement is displaying a dependent field (such as a gate number, companion seat, or discount code) only when that attribute is populated:

  • Configure the dependent field's Visibility Condition (showWhen) as:

{otherFieldKey}

  • Blank / Null Handling: If {otherFieldKey} is null, undefined, empty string "", or whitespace, the expression evaluates to false. Apple Wallet will completely omit the field from the layout, and neighboring fields will gracefully expand to fill the available space.

4. Complete Field Model Specification

Every field attached to a template via request payload supports the following properties:

PropertyTypeAllowed Values / FormatPlatform Behavior & Rules
keystringUnique identifier per pass (e.g. balance_fld)Used by iOS and Android to diff field values across push updates.
labelstringStatic caption or {variable}Displayed in labelColor above or below the value.
value`string \number`Static text, number, ISO date, or {variable}Hydrated at issuance/update time from Pass.attributes, externalId, or system tokens.
changeMessagestringString containing %@ (e.g. "Tier upgraded to %@")Triggers a native iOS lock-screen push alert when value changes; %@ is replaced by the new formatted value.
showWhenstringCondition expression (e.g. {tier} == "VIP")Evaluates visibility dynamically based on passholder attributes.
textAlignmentPKTextAlignmentPKTextAlignmentLeft, PKTextAlignmentCenter, PKTextAlignmentRight, PKTextAlignmentNaturalControls horizontal alignment in Apple Wallet front field columns.
dateStylePKDateStylePKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFullFormats ISO 8601 date strings according to the passholder's device locale.
timeStylePKDateStylePKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFullFormats time components in the passholder's local timezone.
numberStylePKNumberStylePKNumberStyleDecimal, PKNumberStylePercent, PKNumberStyleScientific, PKNumberStyleSpellOutFormats numeric field values with locale-aware thousand/decimal separators.
dataDetectorTypesPKDataDetectorType[]PKDataDetectorTypePhoneNumber, PKDataDetectorTypeLink, PKDataDetectorTypeAddress, PKDataDetectorTypeCalendarEvent, PKDataDetectorTypeNoneEnables interactive tap actions (call, open URL, open Maps, add calendar event) on back fields.
currencyCodestringISO 4217 3-letter code (EUR, USD, GBP, CHF)Formats numeric values as localized currency amounts in Apple & Google Wallet.
attributedValuestringHTML anchor string (<a href="https://...">Label</a>)Supported on Apple Wallet backFields to render clickable web, tel:, or mailto: links.

Apple Wallet attributedValue Anchor Tag Rules

Apple Wallet does not render arbitrary HTML (<b>, <div>, <script>) inside pass fields. Only <a href="...">...</a> anchor tags are permitted inside attributedValue on back fields. Passinstance's serializer (apple-pass-field.serializer.ts) automatically strips unsupported HTML tags and converts valid URLs into clickable linksModuleData entries on Google Wallet.


5. Pass-Level structured JSON attributes & database GIN Indexing

When a pass is created or updated, custom attribute key-value pairs are stored in the attributes structured JSON column on the pass table. To ensure sub-millisecond filtering across millions of passes, Passinstance maintains a dedicated database Generalized Inverted Index (attribute search index) on pass.attributes.

This index powers:

  • High-speed cohort queries via GET /api/v1/passes (filtering by custom properties such as attributes.tier = "VIP" or attributes.city = "Berlin").
  • Real-time audience segmentation in PassProjectSegment and Workflow Automation.
  • Dynamic variable hydration without expensive relational table joins.

6. Troubleshooting Dynamic Fields

Why does my conditional field not appear in the simulator preview?

If a field with a showWhen condition is hidden in the Visual Editor:

  1. 1
    Open the Preview Mock Data drawer in the simulator footer.
  2. 2
    Check the mock attributes currently assigned to the simulator preview.
  3. 3
    If the field requires {memberTier} == "Gold", ensure the mock attribute memberTier is set to "Gold".
  4. 4
    If using existence syntax ({couponCode}), verify that couponCode is populated with a non-empty string in mock data.

Lockscreen push notification does not appear when a field updates

Apple Wallet strictly requires the %@ format specifier in changeMessage:

  • Correct: "Your new balance is %@ points"
  • Broken: "Your points balance was updated" (iOS suppresses notifications lacking %@).

API Reference: Configuring Fields with showWhen Conditions

HTTP Request

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

JSON
{
  "fields": {
    "headerFields": [
      {
        "key": "wallet_balance",
        "label": "BALANCE",
        "value": "{creditBalance}",
        "currencyCode": "EUR",
        "textAlignment": "PKTextAlignmentRight",
        "changeMessage": "Your card balance was updated to %@"
      }
    ],
    "primaryFields": [
      {
        "key": "holder_name",
        "label": "MEMBER",
        "value": "{firstName} {lastName}",
        "textAlignment": "PKTextAlignmentLeft"
      }
    ],
    "secondaryFields": [
      {
        "key": "vip_status",
        "label": "TIER",
        "value": "{memberTier}",
        "showWhen": "{memberTier} |= Gold,Platinum,VIP"
      },
      {
        "key": "companion_seat",
        "label": "COMPANION SEAT",
        "value": "{companionSeat}",
        "showWhen": "{companionSeat}"
      }
    ],
    "backFields": [
      {
        "key": "support_link",
        "label": "CUSTOMER CONCIERGE",
        "value": "https://artisan-roasters.example.com/support",
        "attributedValue": "<a href='https://artisan-roasters.example.com/support'>Contact VIP Concierge</a>"
      }
    ]
  }
}

HTTP Response (200 OK)

JSON
{
  "success": true,
  "data": {
    "id": "tmpl_01hxyz987654321",
    "rowKind": "DRAFT",
    "updatedAt": "2026-11-16T21:00:00.000Z"
  },
  "statusCode": 200
}

Next, learn how to validate completion gates and promote drafts in 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.