How a pass is rendered

Understand when The Wallet Crew renders a pass, which data is used, and how render failures behave.

How a pass is rendered

When The Wallet Crew delivers a pass to Apple Wallet or Google Wallet, it builds the wallet artifact from three inputs: the pass record, the pass template, and data fetched from connected systems. This page explains when rendering is triggered, how the pipeline runs, and what happens when something fails.

Real-world examples

• A loyalty balance changes in the CRM, but the installed pass changes only after a push update or a new render.
• A connector timeout prevents a ticket update from reaching Apple Wallet even though the source system already has the new gate.
• A template path is wrong, so the pass is delivered with a blank field instead of failing completely.

When rendering is triggered

The platform renders a pass in four cases.

1. Add to Wallet — a customer taps an add button and The Wallet Crew generates the Apple .pkpass file or creates or updates the Google Wallet object.
2. Push update — an update is triggered through an API call or connector, the platform rebuilds the pass, then notifies Apple through APNs or Google through the Google Wallet API.
3. Preview — a preview is requested from the back office or from the preview API endpoint.
4. Template render API — the render API is called explicitly with a template and a data context.

Rendering is not continuous. The platform does not poll or rebuild passes on a schedule. A pass reflects the state of the data at the moment the last render was triggered.

The render pipeline

The render pipeline follows a fixed sequence.

1. Load the pass record — The Wallet Crew retrieves the pass record from the database, including its external identifiers, metadata, and additional data.
2. Load the pass template — the YAML template for the pass type is loaded. It defines the field mapping, Liquid expressions, barcode configuration, images, and the data providers to call.
3. Fetch provider data — all configured data providers are called in parallel. Each provider uses the pass identifiers and returns external data that is merged into the render context.
4. Apply Liquid templates — each template field is evaluated against the render context. This produces the final values used for wallet fields.
5. Generate the wallet artifact — resolved values, images, and barcode settings are assembled into the Apple .pkpass bundle or the Google Wallet class and object payload.
6. Deliver — the signed Apple pass is returned to the caller. The Google object is created or updated server to server.

For supported Liquid filters and tags in The Wallet Crew, use Templating engine. For standard Liquid behavior beyond the custom extensions, use the DotLiquid documentation.

What data is available to the template

The Liquid context depends on the pass template and the configured data providers. Common sources are the pass record, additional data stored on the pass, and provider outputs fetched at render time.

• Pass record fields such as pass ID, pass type, creation date, and update date.
• Additional data stored on the pass.
• Provider outputs such as customer.firstName, loyaltyBalance, or offerTitle.

Provider data is fetched at render time. The Wallet Crew does not pre-cache provider output on the pass record. A rendered pass reflects the latest source data available during the last successful render.

Metadata is used for operational segmentation and reporting. It should not be treated as a wallet display source.

What happens when something fails

Data provider unavailable

If a data provider returns an error or times out, the whole render fails. The platform does not fall back to a previous provider value. The update call returns an error and the installed pass is not changed.

Provider failure is the most common cause of a pass update not reaching devices. If an update appears to fail silently, check that provider endpoints are reachable from The Wallet Crew outbound IPs listed on Infrastructure.

Missing Liquid variable

If a Liquid expression references a variable that is not present in the render context, the field resolves to an empty value and the error is logged. Pass generation continues. The pass can still be delivered with a blank field.

Missing or invalid template

If the template for the pass type is missing or contains invalid YAML, generation fails before any provider call starts.

Pass history

The platform records a lifecycle event each time a pass is rendered, updated, or delivered. These events can be queried through Insights API and are also exposed in the Monitoring space.

The platform does not store a snapshot of the rendered pass content. When an audit trail of rendered values is needed, the source of truth remains the upstream systems that supplied the data.

FAQ

Why does a source change not appear immediately on the pass?

The platform does not poll source systems continuously. A render trigger is still required before the installed pass changes.

Does a missing variable always fail the render?

No. Missing variables usually resolve to blank values. Provider failures and invalid templates are more likely to stop the render completely.

Where should render troubleshooting start?

Start with the stored identifiers, the provider health, and the template field paths. Those three areas explain most render defects.