> 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
## Pass data and sync
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.
Understanding this pull model is essential before working with the API or configuring a template. It explains why [external identifiers](/developers-guides/pass-architecture/structure.md) are the most critical field on a pass, why updates that do not trigger a connector call never change what a customer sees, and why connector availability directly affects pass delivery.
Real-world examples
* A loyalty pass stores a CRM ID and fetches the latest balance only when the pass is rendered.
* An event pass stores a ticket ID and fetches the latest seat or gate data when an update is triggered.
* A membership pass stores a local override in additional data when no connected system exposes that value.
### 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 automatically when needed | Recomputed, not manually set | Segmentation and reporting only |
{% 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 %}
### 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.
Use [Structure](/developers-guides/pass-architecture/structure.md) for the back-office view of where these identifiers live on a pass.
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 are not displayed on the pass. Their only purpose is to let connectors fetch the correct record.
If a pass has no external identifier for a connector used by the template, that connector has nothing to query. Its fields are not available at render time.
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) for the full lookup rules.
To use external identifiers in a pass delivery URL, see [Pass delivery URLs](broken://spaces/OnaDC4sjKAx53j0QV843/pages/aIGdnmHyhqKaPDnw0n0G).
{% 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
Passes are created through enrolment flows, not through a later data import step.
The main 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#npm-module).
* **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 [Connector-triggered pass creation](/developers-guides/integration-guides/wallet/connector-triggered-pass-creation.md).
* **Enrolment form** — the platform includes a built-in enrolment form with a pass step. Use [Enrolment flows](/developers-guides/integration-guides/wallet/enrolment-flows.md).
In all cases, external identifiers are set at creation. There is no separate data loading step that later attaches them.
### 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.
{% hint style="info" %}
Connector field names vary by integration. Use the connector reference for the fields exposed by each connector.
{% endhint %}
### 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 can be set in these ways:
* At pass creation through the Cinto SDK, a built-in enrolment flow, or a connector flow that sets pass-level values
* Updated per pass through `PATCH /api/{tenantId}/passes/{passId}` or `PATCH /api/{tenantId}/passes`
* Updated in bulk through `POST /api/{tenantId}/passes/pushUpdate`
* Edited manually in the back-office
Updates are merged into existing additional data. Keys not included in a request are preserved.
Use the [API reference](https://docs.thewalletcrew.io/api-reference/pass-management/pass) for request body details.
### Metadata
Metadata is a set of key-value pairs computed automatically by the platform. It is not set manually and it is not displayed on the pass.
Metadata exists for segmentation and reporting. It makes it possible to group, filter, and target passes with computed values such as a tier, store assignment, or expiry window.
Metadata is recomputed automatically when needed during rendering, updates, and data generation flows. The exact triggers are internal and can change. If a connector fails and required data is unavailable, metadata 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 in four situations:
1. **Pass installation** — a customer adds the pass to a wallet and the pass is built for the first time.
2. **Push update** — an update is triggered through the API or by an integration event. For the first API calls, start with [Getting started with the API](/developers-guides/integration-guides/getting-started-with-the-api.md).
3. **Back-office preview** — a pass preview is requested from the back-office.
4. **Render API** — the render endpoint is called explicitly.
There is no background polling. Outside of these triggers, the installed pass on a device does not change.
Use [How a pass is rendered](/developers-guides/pass-architecture/how-a-pass-is-rendered.md) for the full render pipeline.
### FAQ
Can customer data be sent once and stored in The Wallet Crew?
No. The platform stores only the pass record, identifiers, additional data, and computed metadata. Customer data stays in source systems unless a specific integration is designed otherwise.
Why does a pass still show old data after a source update?
A source change does not update the installed pass by itself. A render trigger is still needed, for example a push update or a new installation.
What is the first field to verify when connector data is missing?
Check the external identifiers on the pass first. If the connector cannot match a source record, its fields will be missing from the render context.
---
# 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/pass-data-and-sync.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.