> 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/api-reference/pass-management.md).

# Pass Management

The core of The Wallet Crew API. These endpoints let you issue, read, update, and manage digital passes across Apple Wallet and Google Wallet — and record the real-world events that drive your loyalty, ticketing, and membership workflows.

The core of The Wallet Crew API. These endpoints let you issue, read, update, and manage digital passes across Apple Wallet and Google Wallet — and record the real-world events that drive your loyalty, ticketing, and membership workflows.

### Pass

The `Pass` tag covers the full lifecycle of a wallet pass.

| Operation                                          | Description                                                                                                               |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `GET /api/{tenantId}/passes`                       | List passes with filtering, sorting, and pagination. Requires `Pass.Read`.                                                |
| `POST /api/{tenantId}/passes`                      | Create a new pass for a customer. Requires `Pass.Write`.                                                                  |
| `PATCH /api/{tenantId}/passes`                     | Update one or more passes by internal ID or external identifiers (e.g. `id.crm.customerId=…`). Triggers a wallet refresh. |
| `PATCH /api/{tenantId}/passes/{passId}`            | Update a single pass by its internal ID.                                                                                  |
| `PUT /api/{tenantId}/passes/{passId}/notification` | Send an Apple Wallet / Google Wallet push notification to a specific pass holder.                                         |

Passes are identified through **external identifiers** that link them to your source systems (CRM ID, loyalty number, ticket ID). Most update endpoints accept external identifiers so you never need to look up the internal `passId` first.

> **Tip — force a data refresh** Set `options.UpdateMetadata = true` in a PATCH body to force a full re-fetch from all configured connectors. Use `options.BypassQueue = true` for synchronous delivery instead of the default async queue.

### Privilege

A **privilege** is a benefit attached to a pass — a discount tier, a reward, a limited-use coupon, an entitlement. Privileges appear on the pass face and can carry a numeric value (points, balance, remaining uses) that changes over time through **movements**.

| Operation                                                      | Description                                                                                       |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `GET /api/{tenantId}/passes/{passId}/privileges`               | List all privileges for a pass.                                                                   |
| `GET /api/{tenantId}/passes/{passId}/privileges/{privilegeId}` | Retrieve a single privilege.                                                                      |
| `POST /api/{tenantId}/passes/{passId}/privileges`              | Create a new privilege on a pass.                                                                 |
| `PUT /api/{tenantId}/passes/{passId}/privileges/{privilegeId}` | Create or update (upsert) a privilege by its ID.                                                  |
| `POST …/privileges/{privilegeId}/movements`                    | Apply a movement (issuance, redemption, adjustment) to a privilege value. Returns a `movementId`. |
| `DELETE …/privileges/{privilegeId}`                            | Permanently delete a privilege.                                                                   |

### Scan

The `Scan` tag records barcode and QR code scan events. When a pass barcode is scanned — at a POS, a venue gate, or a redemption counter — call this endpoint to:

* Correlate the raw scan value to the correct pass.
* Record the scan with a timestamp and symbology type.
* Emit a downstream event to connected systems (Bloomreach, CRM webhooks, etc.).

| Field  | Description                                                                                             |
| ------ | ------------------------------------------------------------------------------------------------------- |
| `data` | The raw decoded barcode/QR value (3–2048 chars). Keep it stable — formatting changes break correlation. |
| `type` | Symbology: `qrcode`, `pdf417`, `code128`, `ean13`, `datamatrix`, `nfc`, or `manual`.                    |

> **Architecture note**: Call the Scan API from a backend relay rather than directly from scanning hardware. This keeps API keys server-side and allows retries, logging, and enrichment.

### Authentication

All endpoints require an `X-API-KEY` header. API keys are tenant-scoped — a key issued for one tenant cannot access another tenant's data. Create and manage keys under **Settings → API Keys & Secrets** in the back-office.

| Scope           | Required for                             |
| --------------- | ---------------------------------------- |
| `Pass.Read`     | Reading pass data                        |
| `Pass.Write`    | Creating, updating passes and privileges |
| `PassScan.Scan` | Recording scan events                    |

### Further reading

* [Getting started with the API](https://docs.thewalletcrew.io/developers-guides/integration-guides/getting-started-with-the-api) — first API call walkthrough
* [Manage pass lifecycle with the API](https://docs.thewalletcrew.io/developers-guides/integration-guides/wallet/pass-lifecycle) — create, update, notify, disable
* [Privilege guide](https://docs.thewalletcrew.io/guides-animation/engage-and-animate/privilege-and-activation/privilege) — privilege types, sources, and movement tracking
* [Scan API guide](https://docs.thewalletcrew.io/developers-guides/integration-guides/scan-api) — integration patterns and troubleshooting


---

# 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/api-reference/pass-management.md?ask=<question>&goal=<endgoal>
```

`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.