> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/developers-guides/pass-architecture/how-a-pass-is-rendered.md).
# How a pass is rendered
## 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](/developers-guides/integration-guides/wallet/liquid-templating.md). For standard Liquid behavior beyond the custom extensions, use the [DotLiquid documentation](https://github.com/dotliquid/dotliquid/wiki/DotLiquid-for-Designers).
### 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`.
{% hint style="info" %}
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.
{% endhint %}
{% hint style="warning" %}
Metadata is used for operational segmentation and reporting. It should not be treated as a wallet display source.
{% endhint %}
### 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.
{% hint style="warning" %}
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](/developers-guides/pass-architecture/infrastructure.md).
{% endhint %}
#### 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](/developers-guides/integration-guides/insights-api.md) 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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.thewalletcrew.io/developers-guides/pass-architecture/how-a-pass-is-rendered.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.