> 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/pass-data-and-sync.md).

# Pass data and sync

Understand what a wallet pass stores in The Wallet Crew, when connector data is fetched, and how render triggers refresh the pass on the phone.

A pass in The Wallet Crew is a thin record. It stores identifiers and a small amount of pass-specific override data. It does not persist customer data from source systems. When a pass is rendered during installation, push update, or preview, connectors call external systems live to fetch the data needed to build the pass.

This pull model explains why [external identifiers](#external-identifiers) are the most critical field on a pass, and why connector availability directly affects pass delivery.

## What a pass stores

A pass record contains only the data needed to identify the pass, fetch external data, and keep small pass-specific values.

| Field type           | Description                                                 | Persisted?                     | Used for                                                |
| -------------------- | ----------------------------------------------------------- | ------------------------------ | ------------------------------------------------------- |
| Pass ID              | Internal platform identifier. Opaque. Assigned at creation. | Yes                            | Internal references, some API endpoints                 |
| External identifiers | Key-value pairs linking the pass to source systems          | Yes                            | Connector lookups at render time                        |
| Additional data      | Key-value pairs stored directly on the pass                 | Yes                            | Enriching the pass when connector data is not available |
| Metadata             | Key-value pairs computed from the pass template             | Recomputed, not set by the API | Filtering, targeting and reporting                      |

{% hint style="info" %}
The Wallet Crew does not store personal data by default. Names, balances, loyalty points, and other customer data stay in source systems and are fetched at render time.
{% endhint %}

Choose the field type by purpose:

* Use **external identifiers** to connect the pass to a source system.
* Use **metadata** to filter and segment passes.
* Use **additional data** to enrich selected passes.

To validate the source data of a pass, open its Data tab in the admin console: it shows which values each connected system provided. See [Pass details](https://docs.thewalletcrew.io/guides-monitoring/monitor/pass-details.md).

## External identifiers

External identifiers are the bridge between a pass and source data. They tell each connector which record to fetch when the pass is built.

The admin console shows them on the pass, see [Pass details](https://docs.thewalletcrew.io/guides-monitoring/monitor/pass-details.md).

A pass can carry several external identifiers, often one per connected system. A loyalty pass might use a CRM customer ID, a Shopify customer ID, and a loyalty program number as separate identifiers. Each key is a string. Each value is the identifier used by that source system.

External identifiers let connectors fetch the correct record. Templates can also read them as `id.<key>`.

External identifiers are also used to locate a pass in the API. Most write endpoints accept `id.{key}={value}` query parameters to target a pass without knowing its internal ID, for example `id.shopify.customerId=12345`. Multiple `id.*` parameters are combined as `AND` conditions. Use the [API reference](https://docs.thewalletcrew.io/api-reference/pass-management/pass.md) for the full lookup rules.

To use external identifiers in a pass delivery URL, see [Download pages](https://docs.thewalletcrew.io/guides-enrolment/enrolment/download-pages.md).

{% hint style="warning" %}
A missing or incorrect external identifier silently prevents a connector from fetching data. If a pass renders with blank fields, verify that the correct external identifiers are set on the pass.
{% endhint %}

## How a pass is created

A pass is created at the moment it is issued. There is no later data import step that creates it.

The creation paths are:

* **Cinto SDK** — a developer calls the SDK during an enrolment flow and provides external identifiers at creation time. Use the [Cinto SDK documentation](https://docs.thewalletcrew.io/guides-enrolment/enrolment/on-your-website.md).
* **Connector** — some connectors can create passes automatically when a relevant event happens in the source system. The connector sets the external identifiers as part of pass creation. Use [Enrolment flows](https://docs.thewalletcrew.io/developers-guides/integration-guides/wallet/enrolment-flows.md#source-driven-creation).
* **Enrolment form** — the platform includes a built-in enrolment form with a pass step. Use [Enrolment flows](https://docs.thewalletcrew.io/developers-guides/integration-guides/wallet/enrolment-flows.md).
* **API** — a backend calls `POST /passes` with identifiers and optional additional data. It needs the `tenant.pass:write` scope, or a proof for each identifier. Use [Pass lifecycle → Creating a pass](https://docs.thewalletcrew.io/developers-guides/integration-guides/wallet/pass-lifecycle.md).

In all cases, external identifiers are set at creation. They can be changed later with `PATCH /passes`.

The four paths end in the same pass record:

```mermaid
flowchart LR
    A["Cinto SDK"] --> P(("Pass record"))
    B["Enrolment form"] --> P
    C["Connector event"] --> P
    D["POST /passes"] --> P
    P --> R["Render when a trigger happens"]
```

## How connectors use external identifiers

Connectors fetch data from source systems. They are configured and activated per tenant as part of the integration setup.

When a pass is rendered, each configured connector receives the relevant external identifier and calls the source system. The response becomes available in the render context as named fields such as `firstName`, `loyaltyBalance`, or `offerTitle`. The exact field names depend on the connector and are documented in that connector's reference.

The connector call happens at render time, not at pass creation. There is no background job pushing customer data into The Wallet Crew. The pass reflects what connectors returned during the last successful render.

## Additional data

Additional data is the escape hatch for values that do not come from a connector.

It is a key-value store attached directly to the pass. Unlike connector data, additional data is persisted on the pass record. It does not depend on a connector call to be available at render time.

Use additional data when a value does not exist in any connected system or when a pass-level override must be stored directly on the pass.

Additional data fields are available in the render context as `additionalData.fieldName`.

Additional data is set at creation (Cinto SDK, enrolment flow, connector, `POST /passes`), updated with the API ([Pass lifecycle → Updating pass data](https://docs.thewalletcrew.io/developers-guides/integration-guides/wallet/pass-lifecycle.md#updating-pass-data), [Batch operations](https://docs.thewalletcrew.io/developers-guides/integration-guides/wallet/batch-operations.md)), or edited manually in the admin console.

## Metadata

Metadata is a set of key-value pairs computed by the platform from the Metadata rows of the pass template (a key and a Liquid value). API calls do not set it, and it is not displayed on the pass.

Metadata exists for filtering, targeting, and reporting. It makes it possible to group and target passes with computed values such as a tier, store assignment, or expiry window. Filters read it as `metadata.<key>`.

Metadata is recomputed when an update runs with `options.updateMetadata` (default `true`; the call is slower). A bulk update sent without a body does not recompute it by default. If a connector fails and required data is unavailable, recomputation can fail too.

{% hint style="warning" %}
Metadata is for operational use only. Do not use it to display information on a pass. Metadata values are not available to wallet display fields.
{% endhint %}

## When data is fetched

Connector data is fetched only when a render is triggered: installation, push update, preview, or a direct call to the template render API. There is no background polling. Outside of these triggers, the installed pass on a device does not change.

Use [How a pass is rendered](https://docs.thewalletcrew.io/developers-guides/pass-architecture/how-a-pass-is-rendered.md) for the four triggers and the full render pipeline. For the first API calls, start with [Getting started with the API](https://docs.thewalletcrew.io/developers-guides/integration-guides/getting-started-with-the-api.md).

## FAQ

<details>

<summary><strong>What is the difference between metadata and additional data?</strong></summary>

Metadata is computed from the pass template and is used for filtering and targeting. Additional data is set on the pass and is used for pass enrichment. If a value must be used for targeting or filtering, expose it as a metadata field in the pass template.

</details>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/developers-guides/pass-architecture/pass-data-and-sync.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
