> 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/structure.md).

# Pass data structure

Understand how pass data is organized in The Wallet Crew, including identifiers, metadata, additional data, and external data.

## Pass data structure

This page explains how pass data is organized in The Wallet Crew. It shows which values are stored on the pass record, which values stay in connected systems, and when to use each field type.

{% hint style="info" %}
The Wallet Crew follows a privacy-first model. Store only the data required for the pass experience and integration workflow. Review each tenant configuration before using personal data in identifiers, metadata, or additional data.
{% endhint %}

<details>

<summary>Real-world examples</summary>

* A loyalty pass can use a CRM customer ID as an external identifier, a `storeId` as metadata, and a campaign message as additional data.
* A ticketing pass can use a ticket ID from the ticketing system, a `venue` metadata field for segmentation, and a seat-upgrade note as additional data.
* A membership pass can combine several identifiers when data comes from more than one system, such as Shopify, Klaviyo, and an internal CRM.

</details>

### What a pass contains

A pass is built from several data blocks. Each block serves a different purpose.

* **General information** describes the pass record itself.
* **External identifiers** connect the pass to other systems.
* **Metadata** supports segmentation and targeting.
* **Additional data** enriches the pass when no source system provides the value.
* **External data** shows the source data used to build the pass.

### General information

The general section contains the core record details for the pass. It includes the creation date, the last update date, Apple Wallet and Google Wallet status, and the pass type.

The pass type is the only value in this section that can be changed manually.

<div data-with-frame="true"><figure><img src="https://4179171865-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOnaDC4sjKAx53j0QV843%2Fuploads%2FoODmwAeJxVzUFS8q0QRJ%2Fdevelop-structure-general-information-pass.png?alt=media&#x26;token=8892e155-0dfa-4ac4-a258-a733b3684156" alt="Pass general information, including creation date, update date, wallet status, and pass type"><figcaption><p>Check the creation and update dates, the Apple Wallet and Google Wallet status, and the pass type, which is the only value here that can be changed manually.</p></figcaption></figure></div>

### External identifiers

External identifiers connect a pass to one or more connected systems. They make it possible to fetch the data needed to build the pass without storing that personal data in The Wallet Crew.

A single pass can contain several identifiers. Each identifier maps to a specific integration point, such as Shopify, Klaviyo, or Cegid Y2.

<div data-with-frame="true"><figure><img src="https://4179171865-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOnaDC4sjKAx53j0QV843%2Fuploads%2Fx2BSzwSL2J9zVdoE1FzG%2Fdevelop-structure-external-identifiers.png?alt=media&#x26;token=80c92093-e663-42af-b733-e8779eaaea62" alt="List of external identifiers attached to a pass"><figcaption><p>Check that one identifier is present for every connected system the pass depends on.</p></figcaption></figure></div>

Identifiers are stored as key-value pairs. This makes it possible to attach the right reference for each source system.

<div data-with-frame="true"><figure><img src="https://4179171865-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOnaDC4sjKAx53j0QV843%2Fuploads%2Fbg0BzE7n53bEqim3oiWq%2Fdevelop-structure-what-type-information-is-available-pass.png?alt=media&#x26;token=b536ed43-0f9d-4936-bc50-7507f2466a5f" alt="Form used to add an external identifier to a pass"><figcaption><p>Check that the identifier key matches the key the source system expects before saving it.</p></figcaption></figure></div>

### Metadata

Metadata is used to segment passes. It helps group passes by operational or marketing criteria.

For example, a `storeId` metadata field can separate passes by location. This makes it possible to target a push notification to passes linked to one store only.

<div data-with-frame="true"><figure><img src="https://4179171865-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOnaDC4sjKAx53j0QV843%2Fuploads%2FYGAZBuCPxCTkp2kGcIC9%2Fdevelop-structure-segment.png?alt=media&#x26;token=ef43d1ba-1e71-4232-9215-c1ded3b1fabe" alt="Metadata fields used to segment passes"><figcaption><p>Check that the fields needed for filtering, targeting, and reporting are present as metadata.</p></figcaption></figure></div>

### Additional data

Additional data is optional pass-level information. It is not required to create the pass and is not intended for segmentation.

This data is useful when a value does not exist in a connected system but still improves the wallet experience. A custom welcome message is a common example.

<div data-with-frame="true"><figure><img src="https://4179171865-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOnaDC4sjKAx53j0QV843%2Fuploads%2FdI8fcLWJKAhr1oTgQVds%2Fdevelop-structure-additional-data-refers-optional-information-that-is.png?alt=media&#x26;token=00218999-133d-41e8-8e5c-61bab6c06831" alt="Additional data attached to a pass for wallet enrichment"><figcaption><p>Check that values kept only on the pass, such as a welcome message, appear here rather than in metadata.</p></figcaption></figure></div>

### External data

External data shows the source information used to build the pass. It helps verify which values were collected and which connected system provided them.

This view is useful for validation and troubleshooting. It makes it easier to confirm that the pass receives the expected data before or after an update.

<div data-with-frame="true"><figure><img src="https://4179171865-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOnaDC4sjKAx53j0QV843%2Fuploads%2F9mo0C7dF9vThQDe6qPQ9%2Fdevelop-structure-external-data-is-simply-all-that-were.png?alt=media&#x26;token=f0f6b011-8646-4a7f-bbcd-0b2b933c526b" alt="External data used to build a pass and its source systems"><figcaption><p>Check which connected system supplied each raw value behind the pass.</p></figcaption></figure></div>

### Choosing the right field type

Choosing the right field type keeps the pass model clean and maintainable.

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

### FAQ

<details>

<summary>Does The Wallet Crew store personal data on the pass record?</summary>

The pass model supports identifiers, metadata, and additional data. Only store personal data when the use case and tenant configuration require it.

</details>

<details>

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

Metadata is designed for segmentation. Additional data is designed for pass enrichment. If a value must be used for targeting or filtering, it belongs in metadata.

</details>

<details>

<summary>Can one pass be connected to several systems?</summary>

Yes. A single pass can contain several external identifiers. Each identifier can represent a different connected system.

</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/structure.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.