# Move passes to The Wallet Crew

Use this guide when you want to move **already-installed** Apple Wallet and Google Wallet passes from another provider to The Wallet Crew.

The goal is continuity for customers. When the migration is done correctly, they keep the same pass on their device, they do not reinstall anything, and your barcode and redemption flow stay unchanged.

Most of the work is coordination, not implementation. You align issuer credentials, export the technical identifiers that tie each pass to its existing Apple/Google record, validate with a small pilot, then run a controlled cutover.

If you need the reverse flow, see [Export passes from The Wallet Crew to another provider](https://docs.thewalletcrew.io/configure/wallet/import-and-export/move-pass-from-and-to-the-wallet-crew/export-passes-from-the-wallet-crew-to-another-provider).

<details>

<summary><strong>Real-world examples</strong></summary>

* A Brand decides to change wallet pass provider, but wants customers to keep their installed passes.
* A Brand replaces an in-house wallet setup with The Wallet Crew to get a more reliable operating layer.
* A Brand changes an underlying system (CRM, loyalty, ticketing, POS) and needs to transfer active passes safely.

</details>

## Before you start

Most migrations succeed or fail based on platform constraints and who controls issuer credentials.

If you want background on identifiers and pass data, read [Structure](https://docs.thewalletcrew.io/develop/architecture/structure).

### Set up your The Wallet Crew project before migrating

You cannot start a migration before your The Wallet Crew project is already working end-to-end.

Migration is not “creating passes again”. It is importing the identifiers that let The Wallet Crew take over updates for passes that are already installed on devices. If your project is not configured, imported passes will exist, but they will not update reliably after cutover.

Before you import anything, make sure:

* You have connected the wallet providers and can sign/own passes (Apple Pass Type ID and certificates, Google Wallet issuer account access).
* You have decided which **external identifiers** you will use to link passes to your systems (customer ID, ticket ID, membership number, order ID, ...). These must be stable over time.
* You can compute pass content from your source of truth (API integration, file workflow, or operational process).
* You can run a full lifecycle on test passes: issue, update a visible field, and verify the update on a real device.

<details>

<summary>Migration readiness checklist</summary>

Use this as a go/no-go list before you touch production passes.

* [ ] You know which Apple Pass Type ID signs the existing passes.
* [ ] You have the Apple credentials needed to keep the same issuer identity.
* [ ] You know the Google Wallet `issuerId` that owns the existing passes.
* [ ] You have access to that issuer account in the Google Pay & Wallet Console.
* [ ] Your current provider can export one row per pass with required identifiers.
* [ ] Your current provider can send an Apple “final update” (see cutover step).
* [ ] You have a pilot batch of 2–3 real passes per platform.
* [ ] You have a rollback plan for Apple (if supported by the old provider).

{% hint style="info" %}
Plan for at least one pilot cycle. Most delays come from exports, approvals, and cutover scheduling.
{% endhint %}

</details>

{% hint style="info" %}
Plan for at least one pilot cycle. Most delays come from exports, approvals, and cutover scheduling.
{% endhint %}

### What you import: pass identifiers (platform + external)

You do not recreate passes during a migration. You import identifiers so The Wallet Crew can update passes that are **already installed** on devices.

You import two kinds of identifiers:

* **Platform identifiers**. These point to the existing Apple/Google pass record.
  * Apple: `serialNumber` + `authenticationToken`
  * Google: object **resource ID** (often called object ID)
* **External identifiers**. These link a pass back to your own systems.
  * Examples: customer ID, ticket ID, membership number, order ID

Platform identifiers let The Wallet Crew update the same pass on the device. External identifiers let you match the pass to the right customer record and keep updates correct after cutover.

A single pass can have multiple external identifiers. This is useful when you reconcile data across systems.

### Decide if you can migrate “in place”

Apple and Google do not allow the same migration patterns.

#### Apple Wallet (in-place is usually possible)

You can usually migrate without reinstall if you keep the same Apple issuer identity (same Pass Type ID / signing identity) and you repoint the pass update endpoint (`webServiceURL`).

This typically requires your current provider to send at least one “final update” to installed passes. That update embeds The Wallet Crew `webServiceURL` so devices start calling The Wallet Crew for future updates.

#### Google Wallet (only if you keep the same issuer account)

Google Wallet passes are tied to a Google Pay & Wallet Console issuer account (`issuerId`).

If the existing passes were created under an issuer account you do not control, you cannot transfer them in place. You must plan a re-issuance flow (new save links, new objects).

{% hint style="warning" %}
For Google Wallet, plan the migration around your issuer account.

If your current provider issued passes under an issuer account you do not control, plan a re-issuance flow.
{% endhint %}

### What you need from your current provider

Ask for one export row per pass. You will use it to attach The Wallet Crew to the *existing* installed pass.

At minimum, get:

* **Apple Wallet**: `serialNumber` and `authenticationToken`
* **Google Wallet**: object **resource ID** (often called “resource ID” or “object ID”)
* A stable customer identifier (email, customer ID, ticket ID). This is how you match passes back to customers.

{% hint style="info" %}
If your current provider can also share the Apple Pass Type ID and the Google `issuerId`, it speeds up the eligibility check.
{% endhint %}

## Migration steps

### Sequence overview (what happens end-to-end)

These diagrams show the control points you need for a clean cutover. The key idea is simple: you import identifiers into The Wallet Crew, then you make sure devices start fetching updates from The Wallet Crew.

{% tabs %}
{% tab title="Apple Wallet" %}
Apple in-place migration usually works if you keep the same Pass Type ID and your current provider can ship a “final update” that changes the pass `webServiceURL` to The Wallet Crew.

```mermaid
sequenceDiagram
  autonumber
  participant Brand as Brand systems
  participant Old as Old provider
  participant TWC as The Wallet Crew
  participant Device as Customer device (Apple Wallet)

  Brand->>Old: Request export (serialNumber, authenticationToken, external IDs)
  Old-->>Brand: Export file / feed
  Brand->>TWC: Import identifiers

  Brand->>Old: Ask for "final update" setting webServiceURL = The Wallet Crew
  Old->>Device: Push update notification
  Device->>Old: Fetch updated pass package
  Old-->>Device: Pass updated with new webServiceURL

  Brand->>TWC: Update pass data after cutover
  TWC->>Device: Push update notification
  Device->>TWC: Fetch updated pass package
  TWC-->>Device: Updated pass content
```

{% endtab %}

{% tab title="Google Wallet" %}
Google in-place migration works only if the existing passes belong to an `issuerId` you control. In that case, The Wallet Crew updates the same object resource IDs.

```mermaid
sequenceDiagram
  autonumber
  participant Brand as Brand systems
  participant Old as Old provider
  participant TWC as The Wallet Crew
  participant Google as Google Wallet
  participant Device as Customer device (Google Wallet)

  Brand->>Old: Request export (object resource ID, external IDs)
  Old-->>Brand: Export file / feed
  Brand->>TWC: Import identifiers (resource IDs)

  Brand->>TWC: Update pass data after cutover
  TWC->>Google: Update existing object (same issuerId)
  Google-->>Device: Customer sees updated pass content after sync
```

{% endtab %}
{% endtabs %}

{% stepper %}
{% step %}

### Configure The Wallet Crew issuer credentials

You need The Wallet Crew to authenticate as the same “issuer” as the existing passes.

* For Apple, use the same Pass Type ID as your current provider whenever possible. Then configure certificates.\
  Follow: [Apple Wallet certificates](https://docs.thewalletcrew.io/configure/wallet/apple-and-google-wallet/apple-wallet-certificates).
* For Google, confirm which Google Wallet issuer account owns the existing passes. You need access to that issuer account.\
  Follow: [Google Wallet account](https://docs.thewalletcrew.io/configure/wallet/apple-and-google-wallet/google-wallet-account).
  {% endstep %}

{% step %}

### Export pass technical identifiers from your current provider

Ask your current provider for one export row per pass.

At minimum, export:

* Apple: **serial number** and **authentication token**
* Google: **resource ID** (or object ID)
* Your external identifiers (so you can match each pass to the right customer)
  {% endstep %}

{% step %}

### Import those passes into The Wallet Crew

Import the exported identifiers into The Wallet Crew so each pass record can be linked to its existing Apple/Google identifiers.

Start with [Import & Export](https://docs.thewalletcrew.io/configure/wallet/import-and-export). If you need a file-based bulk update flow, see [Update pass using flat files](https://docs.thewalletcrew.io/configure/wallet/import-and-export/update-pass-using-flat-files).

{% hint style="info" %}
Migration imports often require extra columns (Apple auth token, Google resource ID).

If you don’t see how to map those fields in your tenant, ask The Wallet Crew team to confirm the expected file format.
{% endhint %}
{% endstep %}

{% step %}

### Cut over: repoint Apple pass updates to The Wallet Crew

Apple Wallet passes fetch updates from the `webServiceURL` embedded in the pass.

To migrate without reinstall, your current provider must update `webServiceURL` on the existing passes and trigger an update so devices download the new pass version.

{% hint style="warning" %}
Do not shut down your previous provider’s Apple web service until you have validated cutover on real devices.

If the old endpoint stops responding before devices receive the “final update”, passes may stop updating.
{% endhint %}

Ask your old provider to bulk update all existing passes so their `webServiceURL` matches The Wallet Crew `webServiceURL` :

> `https://api-passd.neostore.cloud/api/<tenantId>/passes/apple`

replace `<tenantId>` by your tenantId, confirm the value with The Wallet Crew support team.
{% endstep %}

{% step %}

### Validate on a small sample

Pick 2–3 passes on each platform.

Update a visible field through The Wallet Crew. Then verify it updates on devices.

If you need to accelerate refresh during testing, run a push update from The Wallet Crew. This is useful on both platforms: Apple devices fetch the updated pass package, and Google users see the updated object sooner.
{% endstep %}

{% step %}

### Monitor after cutover

Monitor updates and redemption for a few days. Keep a rollback option if your previous provider supports it.

For Apple, rollback usually means switching `webServiceURL` back and triggering an update. Do not attempt this unless you have a confirmed working endpoint on the old provider.
{% endstep %}
{% endstepper %}

## Common pitfalls

Apple and Google failures look different. These checks catch most issues early.

### Apple Wallet

If customers report that passes stop updating after cutover, it is usually one of these:

* The `webServiceURL` was not updated on the installed passes.
* The old provider updated `webServiceURL` but did not trigger a push update.
* The Wallet Crew Apple credentials do not match the original pass identity (Pass Type ID / certificate).

### Google Wallet

If updates fail on Google, it is usually one of these:

* The existing passes belong to a different `issuerId`.
* The exported “resource ID” does not match the object IDs being updated.
* The Google Pay & Wallet Console permissions do not allow updates from The Wallet Crew credentials.

## FAQ

<details>

<summary><strong>Do customers need to reinstall their pass?</strong></summary>

Usually no.

If you repoint the Apple `webServiceURL` correctly, existing passes keep updating in place.

For Google, if you keep the same issuer account and resource IDs, users typically keep the same pass.

</details>

<details>

<summary><strong>Why do we need the Apple authentication token?</strong></summary>

Apple uses the authentication token to authenticate update requests for a given serial number.

Without it, a new provider cannot reliably serve updates to the same installed pass.

</details>

<details>

<summary><strong>Can we migrate Google Wallet passes between issuer accounts?</strong></summary>

Not in-place.

Google Wallet passes are tied to the issuer account. If the issuer changes, plan a re-issuance flow.

</details>

<details>

<summary><strong>How do we know the Apple cutover worked?</strong></summary>

Update a visible field in The Wallet Crew and confirm the change on a real device. If you can, also confirm the installed pass is calling The Wallet Crew endpoint by checking server logs or by asking The Wallet Crew Support to confirm traffic.

</details>

<details>

<summary><strong>What if we can’t keep the same Apple Pass Type ID?</strong></summary>

Plan for re-issuance.

If the Apple issuer identity changes, customers usually need to add a new pass. Run a controlled rollout and keep the old pass valid for a transition period when possible.

</details>

<details>

<summary><strong>What if our current provider can’t send the Apple “final update”?</strong></summary>

You may not be able to migrate Apple passes in place.

Without a final update, installed passes keep calling the old `webServiceURL`. In that case, you must either keep the old endpoint running, or plan a re-issuance flow.

</details>

<details>

<summary><strong>Do we need to change barcodes or redemption logic?</strong></summary>

Not necessarily.

If you keep the same pass identifiers and you keep generating the same barcode payload, your in-store or gate scanning flow can stay unchanged. Validate this explicitly during the pilot by scanning migrated passes in real conditions.

</details>

<details>

<summary><strong>What should we communicate to customers during the migration?</strong></summary>

If the migration is in-place, you usually don’t need to communicate anything. Customers keep the same pass and it keeps updating.

If you must re-issue passes, communicate the new “Add to Wallet” flow clearly and early. Keep it short and focus on what customers need to do.

</details>