Liquid templating

Render dynamic pass fields, format values, and build wallet pass content with Liquid.

Liquid templating

Liquid combines fixed text with dynamic values from a pass. The Wallet Crew uses the DotLiquid implementation, plus custom date filters and the minify tag.

Use this reference after confirming the required data paths on a real pass.

Real-world examples

• A loyalty card displays a safe, whole-number points balance.
• A gift card displays its identifier, amount, and expiry.
• An event ticket turns seat data into venue directions.

Confirm available data

Each render receives a data context. It can contain pass data, additional data, and values returned by connected providers.

Inspect View data on a real pass before writing a template. This payload is the source of truth for variable paths.

Additional data is suitable for visible pass content. Metadata supports operations and segmentation. It should not be treated as a wallet display source.

For the complete update and validation flow, see Update pass data in templates.

Common paths include:

Data	Example paths
Customer	firstName, lastName, address.city
Pass	serialNumber, tenantId, publicUrl, authenticationToken
Loyalty	loyalty.points, pendingLoyaltyPoints, loyalty.amounts
Gift card	voucher.amount, voucher.currency, id.y2.giftCardId
Event ticket	ticket.name, ticket.startDate, ticket.seatNumber, ticket.entrance
Collections	y2.tickets, y2.bons.loyaltyCertificates
Custom values	additionalData.<key>

Missing values render as an empty string. Use default when a visible fallback is required.

{{ loyalty.points | default: 0 | floor }}

Syntax basics

Use {{ ... }} to print a value. Use {% ... %} for logic that does not print on its own.

Welcome {{ firstName | default: "member" }}!
{% if loyalty.points and loyalty.points > 1000 %}VIP member{% endif %}
{% assign label = ticket.priceCategory | strip %}

Filters run left to right. Dot notation follows the nested structure in the data payload.

Conditions and loops

Liquid treats only nil and false as falsy. The number 0 and the string "false" are truthy. Compare optional numbers explicitly.

{% if pendingLoyaltyPoints and pendingLoyaltyPoints > 0 %}
Pending: {{ pendingLoyaltyPoints }} pts
{% endif %}

Guard loops with a collection-size check. This prevents empty section headings.

{% if y2.tickets.size > 0 %}
  {% for ticket in y2.tickets %}
    - #{{ ticket.ticketNumber }} on {{ ticket.startDate | date: "D" }}
  {% endfor %}
{% endif %}

Inside a loop, forloop.index, forloop.first, forloop.last, and forloop.length are available.

Assignments, branches, and whitespace

Use assign to reuse calculated values. Use case for code-to-label mappings.

{% assign category = ticket.priceCategory | strip %}
{% case category %}
  {% when "F" %}Full price
  {% when "R" %}Reduced
  {% else %}{{ category }}
{% endcase %}

Use {%- and -%} to trim surrounding whitespace. This keeps multi-line templates compact in narrow wallet fields.

{%- assign alley = ticket.alley | strip -%}
{%- if alley -%}Alley {{ alley }}{%- endif -%}

YAML values

Quote Liquid values containing YAML special characters. Use |- for multi-line values.

alternateText: 'Present at checkout: {{ id.y2.customerId }}'
value: |-
  {% assign name = firstName | append: " " | append: lastName %}
  {{ name }}

Custom filters

Date filters

All date filters parse the input as a date or time value, apply the operation, and return a DateTimeOffset. Chain them with | date: "format" when a string output is needed.

add_minutes

Adds the specified number of minutes.

{{ someDate | add_minutes: 60 }}
{{ someDate | add_minutes: 60 | date: "yyyy-MM-dd HH:mm:ss" }}

add_hours

Adds the specified number of hours.

{{ someDate | add_hours: 24 }}
{{ someDate | add_hours: 24 | date: "yyyy-MM-dd HH:mm:ss" }}

add_seconds

Adds the specified number of seconds.

{{ someDate | add_seconds: 3600 }}
{{ someDate | add_seconds: 3600 | date: "yyyy-MM-dd HH:mm:ss" }}

add_days

Adds the specified number of days.

{{ someDate | add_days: 7 }}
{{ someDate | add_days: 7 | date: "yyyy-MM-dd" }}

add_timespan

Adds a timespan in hh:mm:ss format.

{{ someDate | add_timespan: "02:30:00" }}
{{ someDate | add_timespan: "02:30:00" | date: "yyyy-MM-dd HH:mm:ss" }}

All date filters use invariant culture for parsing and formatting.

Format filter

format

Applies a format string to any IFormattable value such as numbers, dates, and enums.

{{ loyaltyPoints | format: "N0" }}

This renders a grouped integer such as 1,234 in invariant culture.

{{ balance | format: "C2" }}

This renders a currency-style value with two decimals.

Custom tag

minify

Generates a short redirect URL from a rendered pass link.

{% minify https://yoursite.com/account/{{ customer.id }} %}

The tag first renders the nested expression, then creates a short URL through The Wallet Crew redirect service, and finally outputs the shortened URL string.

Validate and troubleshoot templates

A variable renders blank

A missing path does not fail the render. It resolves to an empty string. Inspect View data on a real pass, then use default where needed.

{{ loyalty.points | default: 0 }}

A missing variable usually produces a blank field. Validate field paths against a real pass context before publishing a template change.

A date is shifted or formatted unexpectedly

Dates contain time-zone information. Format the intended output explicitly. Use add_hours only when a known offset is required.

{{ ticket.startDate | date: "yyyy-MM-dd" }}
{{ ticket.startDate | add_hours: 2 | date: "HH:mm" }}

format ignores the pass locale

This is expected. format uses invariant culture. Use date for locale-aware dates. Assemble locale-specific number or currency text in each locale file when needed.

A YAML file does not parse

Quote Liquid values containing :, {, #, or &. Use |- for multi-line values.

A condition behaves unexpectedly

The number 0 and string "false" are truthy. Compare optional numeric values explicitly.

{% if loyalty.points and loyalty.points > 0 %}…{% endif %}

Output has blank lines

Use whitespace-control hyphens around the tags.

{%- if ticket.alley -%}
  Alley {{ ticket.alley }}
{%- endif -%}

Literal Liquid syntax is required

Use raw and endraw.

{% raw %}{{ this is literal }}{% endraw %}

The template contains a syntax error

Invalid Liquid can render an error message instead of the intended value. Treat parse errors as template defects and fix them before publication.

Use the pass preview in the back-office to test Liquid expressions against real pass data before deploying a template change to production.

For render timing and failure handling outside Liquid itself, see How a pass is rendered.

Standard filters

Standard DotLiquid filters transform strings, numbers, dates, and collections.

Strings

Filter	Example
default	{{ loyalty.points | default: 0 }}
upcase, downcase, capitalize	{{ firstName | capitalize }}
strip, lstrip, rstrip	{{ ticket.name | strip }}
append, prepend	{{ publicUrl | append: tenantId }}
replace, remove	{{ ticket.name | replace: "VIP", "Premium" }}
truncate, truncatewords, slice	{{ id.y2.customerId | slice: 0, 4 }}
split	{{ "a,b,c" | split: "," }}

Use an empty truncation suffix to create an initial:

{{ firstName | truncate: 1, "" | upcase | append: ". " }}{{ lastName | upcase }}

Numbers and collections

Filter	Example
floor, ceil, round	{{ loyalty.points | default: 0 | floor }}
plus, minus, times, divided_by, modulo	{{ loyalty.points | divided_by: 100 | floor }}
abs, at_least, at_most	{{ balance | at_least: 0 }}
size, first, last, join	{{ tags | join: ", " }}
sort, reverse, uniq, compact	{{ items | sort | reverse }}
map, where	{{ y2.tickets | map: "ticketNumber" | join: ", " }}

Dates, URLs, and HTML

The date filter formats date values for the pass locale.

Expression	Typical output
{{ ticket.startDate | date: "D" }}	Monday, 27 May 2026
{{ ticket.startDate | date: "d" }}	27/05/2026
{{ ticket.startDate | date: "M" }}	27 May
{{ ticket.startDate | date: "t" }}	20:00
{{ ticket.startDate | date: "yyyy-MM-dd HH:mm" }}	2026-05-27 20:00

Use url_encode and url_decode for URL values. Use escape, escape_once, or strip_html for HTML email values.

For the complete filter list, see the DotLiquid reference.

Recipes

The following patterns solve common loyalty, gift-card, and event-ticket needs. Confirm all data paths before use.

Loyalty cards

Display points safely

default prevents a blank balance. floor prevents unwanted decimal points.

{{ loyalty.points | default: 0 | floor }}

Show pending points separately

Only render the pending line when points await validation.

Available: {{ loyalty.points | default: 0 | floor }} pts
{% if pendingLoyaltyPoints and pendingLoyaltyPoints > 0 %}
Pending: {{ pendingLoyaltyPoints }} pts
{% endif %}

Create a repeating stamp counter

modulo resets the visible counter after each reward.

{{ additionalData.stampCount | default: 0 | modulo: 10 }} / 10

The same pattern can select a matching image:

stamp_{{ additionalData.stampCount | default: 0 | modulo: 10 }}.png

Show progress to the next reward

Calculate the remaining points from an editable threshold.

{% assign threshold = additionalData.next_tier_threshold | default: 100 %}
{% assign missing = threshold | minus: loyalty.points %}
{{ missing | at_least: 0 }} pts to {{ additionalData.next_tier_name | default: "your next reward" }}

Derive a tier name

This pattern works when the source provides only a points balance.

{% assign points = loyalty.points | default: 0 %}
{% if points >= 5000 %}Gold member
{% elsif points >= 1000 %}Silver member
{% else %}Welcome member
{% endif %}

List available vouchers

Render vouchers on the back of the card. An else branch makes the empty state clear.

{% if y2.bons.loyaltyCertificates.size > 0 %}
  Your vouchers:
  {% for voucher in y2.bons.loyaltyCertificates %}
    - Voucher of {{ voucher.amount }} € (expires {{ voucher.validity.endDate | date: "D" }})
  {% endfor %}
{% else %}
  No vouchers available yet.
{% endif %}

Gift cards

Reuse one identifier

Use the same value for the barcode and manual-entry fields.

barCodeValue: '{{ id.y2.giftCardId }}'
barCodeAlternateText: '{{ id.y2.giftCardId }}'
cardNumber: '{{ id.y2.giftCardId }}'

Display a variable amount

This uses an optional gift amount and a safe fallback.

value: '{{ additionalData.giftAmount | default: 50 }}'

Keep amount and currency separate

Dedicated fields let wallet platforms apply local currency formatting.

value: '{{ voucher.amount }}'
currencyCode: '{{ voucher.currency }}'

Set the validity window

Use the source dates for expiry and relevance.

relevantDate: '{{ startDate }}'
expirationDate: '{{ expirationDate }}'
start: '{{ startDate }}'
end: '{{ expirationDate }}'

Event tickets

Expire after the event

Expiry on the following day avoids time-zone and late-arrival issues.

expirationDate: '{{ ticket.startDate | add_days: 1 | date: "d" }}'

Set a relevance window

This helps wallet platforms surface the ticket at the right time.

start: '{{ ticket.startDate | add_days: 0 | date: "d" }}'
end: '{{ ticket.startDate | add_days: 1 | date: "d" }}'

Display the event date and time

Separate fields allow the wallet layout to prioritise date or time.

l$label-date-apple: '{{ ticket.startDate | date: "M" }}'
l$value-date-apple: '{{ ticket.startDate | date: "t" }}'

Map category codes

case converts source codes into readable, locale-specific labels.

{% assign category = ticket.priceCategory | strip %}
{% case category %}
  {% when "F" %}Full price
  {% when "R" %}Reduced
  {% when "S" %}Student
  {% when "C" %}Child
  {% else %}{{ category }}
{% endcase %}

Build venue directions

Clean optional fields before concatenating them. Whitespace control keeps the output compact.

{%- assign zone3 = ticket.zone3 | strip -%}
{%- assign zone4 = ticket.zone4 | strip -%}
{%- assign alley = ticket.alley | strip -%}
{%- assign entrance = ticket.entrance | strip -%}
{%- assign location = zone3 | append: " " | append: zone4 -%}
{%- if alley -%}
  {%- assign location = location | append: " - Alley " | append: alley -%}
{%- endif -%}
{{ location }}
{% case entrance -%}
  {%- when "1", "2", "3", "4", "5", "6" -%}Door 1 · Elevator 2
  {%- when "7", "8" -%}Door 1 side · Elevator 1
  {%- when "9", "10", "11", "12" -%}Door 2 · Elevator 4
  {%- when "13", "14", "15", "16" -%}Door 3 · Elevator 6
{%- endcase -%}

List tickets on a multi-ticket pass

This is useful for grouped purchases and multi-event passes.

{% if y2.tickets.size > 0 %}
  Your tickets:
  {% for ticket in y2.tickets %}
    - #{{ ticket.ticketNumber }} for {{ ticket.amount }} € on {{ ticket.creationDate | date: "D" }}
  {% endfor %}
{% endif %}

Create an authenticated deep link

Only use this pattern where the destination supports the pass authentication flow.

Update your profile <a href="{{ publicUrl }}{{ tenantId }}/mobile?neo.authToken={{ authenticationToken }}">here</a>.

FAQ

Is Shopify Liquid fully supported?

No. The Wallet Crew uses DotLiquid plus the custom extensions documented on this page. Shopify-specific extensions should not be assumed to work unless they are documented here.

How can the correct variable path be found?

Use a real pass, inspect View data, then validate the expression in preview. This avoids guessing field names from memory.

Why does a field render blank instead of failing?

Missing variables usually resolve to an empty string. Liquid syntax errors behave differently and should be treated as template defects.