> For the complete documentation index, see [llms.txt](https://help.dollarlabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.dollarlabs.io/dollarback-store-credit/integrations/wallet-passes.md).

# Wallet passes

{% hint style="info" %}
**Plan:** Enterprise plan.
{% endhint %}

Give customers a loyalty card in **Google Wallet or Apple Wallet** that shows their live store-credit balance, name, and tier. It updates automatically when DollarBack credits or debits their balance, and can push a notification to their phone.

One configuration drives both platforms. Most of the setup is shared; the images and a few branding controls are per-platform, because Google and Apple render passes differently.

## Prerequisites

* Customer account blocks active, since customers add the pass from their account profile ([Customer account blocks](https://help.dollarlabs.io/dollarback-store-credit/widgets-and-storefront/customer-account-blocks.md)).
* Your logo and hero images uploaded to **Shopify Files** (**Shopify admin → Content → Files**). You pick them with a file browser, so nothing needs to be hosted elsewhere.

You do **not** need a Google Pay or Apple Developer account. DollarBack signs and issues both pass types for you.

## Set up the pass

Go to **DollarBack admin → Integrations**, find the **Wallet passes** card, and click **Configure**. The page is titled *"Wallet passes — Configure the loyalty card customers add to Google or Apple Wallet"*, and is organised into collapsible sections.

<figure><img src="https://2844543096-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcVBfwy7Yj4tU8TsxkHEr%2Fuploads%2Fgit-blob-0b10d69ca7cb3037bb7831eb97c834b6c3820a66%2Fdb-wallet-general-branding-annotated.png?alt=media" alt="The Wallet passes settings page with an Enabled switch, the General section (Issuer name, Program name, Launch URL), the Branding section (Background color, Text color, Label color, Hide brand name in heading), and a Preview panel with Google and Apple tabs showing a green loyalty card."><figcaption><p>Turn wallet passes on, fill in the General and Branding sections, and check the preview on both the Google and Apple tabs.</p></figcaption></figure>

### Turn wallet passes on

The **Wallet passes** card at the top of the page has a switch and a badge that reads **Enabled** or **Disabled**. The switch is **off by default**, and it is the switch that lets customers get a pass. Turn it on and click **Save**.

While it is off, the **Add to Google Wallet** and **Add to Apple Wallet** buttons still show in the customer's account, but a tap gives no pass: the block shows the message *Wallet pass is not enabled for this shop* instead. If customers report that message, this switch is off.

### General

| Field        | What it is                                                                                                                                     | Limit          |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| Issuer name  | Your business name, shown on the card                                                                                                          | 255 characters |
| Program name | The loyalty program name, the card's headline                                                                                                  | 60 characters  |
| Launch URL   | A link carried on the pass. Google shows it in the links section; Apple puts it on the back of the pass. Your loyalty page is the usual choice | (none)         |

### Branding

| Field                      | Applies to                                                               |
| -------------------------- | ------------------------------------------------------------------------ |
| Background color           | Both platforms (defaults to green)                                       |
| Text color                 | **Apple Wallet only** — Google Wallet picks its own text colors          |
| Label color                | **Apple Wallet only** — Google Wallet picks its own text colors          |
| Hide brand name in heading | **Apple Wallet only** — Google Wallet always shows the organization name |

### Images

The two platforms need differently shaped images, so they have a section each. Click a slot to open the Shopify file browser and pick an upload.

| Apple Wallet          | Google Wallet         |
| --------------------- | --------------------- |
| Logo — 480×150        | Logo — 660×660        |
| Icon — 480×480        | Hero image — 1032×336 |
| Hero image — 1125×432 |                       |

<figure><img src="https://2844543096-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcVBfwy7Yj4tU8TsxkHEr%2Fuploads%2Fgit-blob-4f8a1eea75f64e52f2b07411581e1a24f71cf884%2Fdb-wallet-images-annotated.png?alt=media" alt="The Apple Wallet images and Google Wallet images sections, with empty slots for Logo, Icon and Hero image (Apple) and Logo and Hero image (Google), each with a Choose image button." width="560"><figcaption><p>Each wallet has its own image slots. Click Choose image to pick a PNG from Shopify Files.</p></figcaption></figure>

{% hint style="warning" %}
**Apple images must be PNG.** Apple Wallet embeds the file inside the signed pass and skips anything that isn't a PNG, so a JPG simply won't appear — with no error to tell you why. The **Icon** slot is Apple-only and required for a pass to look finished: it's what shows on the lock screen and in notifications.
{% endhint %}

### Customer notifications

Push notifications sent to the customer's device when their balance changes. **Off by default** — turn them on here if you want them.

There are two messages, **When earned** (credit) and **When redeemed** (debit), each with a **Header** (up to 35 characters) and **Body** (up to 300 characters). Both accept variables:

| Variable         | Renders as                                                                                                                         |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `{amount}`       | The amount just earned or redeemed                                                                                                 |
| `{balance}`      | The customer's new balance                                                                                                         |
| `{programName}`  | Your program name. **When earned** only: in the **When redeemed** message it is not replaced and shows as the text `{programName}` |
| `{customerName}` | The customer's name                                                                                                                |
| `{tier}`         | The customer's current loyalty tier                                                                                                |

Example earned body: `You just earned {amount}! Your {programName} balance is now {balance}.`

<figure><img src="https://2844543096-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcVBfwy7Yj4tU8TsxkHEr%2Fuploads%2Fgit-blob-5fe233906b2c27b4ae1bd757b303b900f061547c%2Fdb-wallet-notifications-annotated.png?alt=media" alt="The Customer notifications section with When earned and When redeemed tabs, a checked box to send a push when a customer earns cashback, Header and Body fields, variable chips and a Send test notification button, and a collapsed Campaign section marked Google Wallet only." width="560"><figcaption><p>Turn on the push message for each event, write the header and body with variables, and send a test to your own pass first.</p></figcaption></figure>

Use **Send test notification** to fire one at a pass you hold yourself before going live.

{% hint style="warning" %}
**The two platforms treat these very differently.** Headers and the **When redeemed** message are Google Wallet only. Apple has exactly one notification — a "change message" baked into the pass when it's issued — and DollarBack builds it from your **When earned** body.

What this means on Apple:

* **Apple always has a change message, even with notifications off.** If **When earned** is off or its body is empty, DollarBack uses the default *"Your balance is now …"*. Turning notifications off does not silence Apple; iOS decides whether to show the message.
* **`{amount}` doesn't work.** When the device pulls an update, the per-transaction amount is unknowable, so a body containing `{amount}` falls back to the same default. Write the earned message around `{balance}` if you want your own wording on iPhone.
* **DollarBack adds the balance for you.** iOS only shows a change message that contains the new balance. If your body doesn't use `{balance}`, DollarBack adds the balance at the end of the message.
* `{customerName}` and `{tier}` render empty in the Apple message. Keep them out of it.

Google notifications use your copy as written, on both messages.
{% endhint %}

{% hint style="warning" %}
Google's wallet policy does not allow links in pass messages. Any URL you paste into a notification text is stripped before the message is sent. Keep the text self-contained — the **Launch URL** field is the supported way to give customers somewhere to tap.
{% endhint %}

### Campaign

A one-off push to **every customer who has added the pass**, with its own Header (35 characters) and Body (300 characters). Useful for a flash sale or a program change.

{% hint style="danger" %}
**Campaign is Google Wallet only, and there is no undo.** Once sent, it's on every Google Wallet holder's phone. Proofread the copy, and remember that a campaign counts against each recipient's daily notification quota (below).
{% endhint %}

### Preview and save

The preview panel has **Apple** and **Google** tabs so you can see each rendering as you edit — worth checking both, since the same images and colors land quite differently. Click **Save** when you're happy. If the **Wallet passes** switch is on, customers can then add the pass.

## What the pass shows

The card displays your program and issuer name, the customer's credit balance, their member name and tier, and a QR code carrying their customer ID, scannable at POS to look the customer up.

## Scan at POS

DollarBack adds a **Wallet Pass Scan** tile to Shopify POS, so staff can open a customer's profile from their wallet pass.

1. In the Shopify POS app, add the **Open customer** tile (*Scan or enter a wallet pass*) to your POS home screen, if it isn't there already. You do this in POS like any other app tile.
2. When a customer shows their pass, tap the tile, then tap **Scan wallet pass** and point the camera at the QR code on the pass.
3. The scan fills in **Customer ID**. Tap **Open customer** to go to that customer's profile in POS.

Staff can also type the numeric customer ID by hand and tap **Open customer**. If the field holds anything other than digits, the tile shows *Enter a numeric customer ID, or scan a wallet pass.*

The tile only opens the customer. Store credit is spent at POS the normal Shopify way, once the customer is on the sale.

The pass currency follows the customer's resolved currency (their last order's presentment currency, falling back to their credit account, then your shop currency), so a customer who shops your store in EUR sees a EUR balance even if your shop currency is USD.

## How customers add it

In their account, on the profile page's wallet block, the customer taps **Add to Google Wallet** or **Add to Apple Wallet**. Both buttons show; the customer picks the one that suits their phone, and the labels are editable like the rest of the block's copy.

<figure><img src="https://2844543096-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcVBfwy7Yj4tU8TsxkHEr%2Fuploads%2Fgit-blob-ee2db1fcedb56ccde2338385fbee303263ac09ad%2Fdb-cx-account-profile.png?alt=media" alt="Customer account profile page with a Loyalty card block (Add your loyalty card to your phone&#x27;s wallet to see your balance and tier on the go, with Add to Google Wallet and Add to Apple Wallet buttons), then a referral block and a Redeem rewards block." width="560"><figcaption><p>Your customers add the pass from the Loyalty card block on their profile page.</p></figcaption></figure>

Each link is signed and generated per customer, and every issued pass is tracked individually.

* **Google:** on a phone the pass lands straight in the Google Wallet app; from a desktop browser, Google prompts the customer to save it to their account.
* **Apple:** the button downloads a signed `.pkpass` file. On an iPhone or iPad it opens in Wallet and the customer taps **Add**. Downloading it on a desktop is not useful — the file needs an Apple device to open, so point iPhone customers at their phone.

## Live updates and the notification quota

Every credit and debit that DollarBack makes updates the pass balance on both platforms: cashback and other rewards, refund and cancellation clawbacks, tier changes, and CSV, API and Flow credits and debits.

{% hint style="info" %}
**Changes made in Shopify admin don't update the pass.** When you add or remove credit directly in **Shopify admin** on the customer's page, DollarBack does not see that change, so the pass keeps showing the old balance. It catches up the next time DollarBack credits or debits that customer, because each update shows the live balance at that moment. To change a balance and update the pass at once, credit or debit the customer through DollarBack.

Store credit that a customer spends at checkout does update the pass: DollarBack sees the payment and refreshes the balance shown.
{% endhint %}

Notifications behave differently:

{% hint style="warning" %}
Google caps push-notifying updates at **3 per pass per 24 hours**. Beyond that, the pass keeps updating silently: the balance stays correct, but no notification appears on the device until the 24-hour window resets. If a customer reports "wallet notifications stopped working" on a busy shopping day, it's this quota, not a bug. Campaign broadcasts count against each recipient's cap too.
{% endhint %}

Apple has no equivalent cap, but it also gives you far less control: iOS decides whether to surface the change message, and you cannot turn it off from DollarBack. Treat the Apple notification as a nice-to-have rather than a channel you can rely on.

## Verify it works

1. Sign in to your storefront as a test customer, open the account profile block, and add the pass to a real device — ideally one of each platform.
2. Credit the customer (a test order or manual credit): within a few minutes the pass balance updates and the Earned notification arrives, assuming a Google pass is under its 3-push daily quota.
3. Check the QR code scans and resolves to the right customer before you tell your POS staff about it.

## Common issues

* The add-to-wallet buttons don't appear: the wallet block isn't active in the customer account editor; see [Customer account blocks](https://help.dollarlabs.io/dollarback-store-credit/widgets-and-storefront/customer-account-blocks.md).
* Tapping an add-to-wallet button shows *Wallet pass is not enabled for this shop*: the **Wallet passes** switch is off. Turn it on and click **Save** ([Turn wallet passes on](#turn-wallet-passes-on)).
* The pass balance is wrong after you changed credit in Shopify admin: changes made directly in Shopify admin don't update the pass. It catches up at the customer's next DollarBack credit or debit.
* The Google **When redeemed** notification shows `{programName}` as text: that variable works only in **When earned**. Remove it from the redeemed message.
* iPhone customers get a balance notification although notifications are off: Apple always carries a change message. See [Customer notifications](#customer-notifications).
* Images don't show on the Apple pass: the file isn't a PNG, or the slot is empty. Apple skips anything that isn't PNG without reporting an error.
* Images look stretched or cropped: the two platforms need different shapes. Fill both image sections rather than reusing one set.
* The Apple notification says something you didn't write: your **When earned** body contains `{amount}`, so it fell back to the default. Rewrite it around `{balance}`.
* Balance updates but no notification: notifications are off by default, or a Google pass has hit its 3-push per 24h quota.
* A link in the notification text disappeared: URLs are stripped per Google policy. Use **Launch URL** instead.
* The `.pkpass` file downloads but won't open: it was opened on a desktop rather than an iPhone or iPad.

## Related articles

* [Customer account blocks](https://help.dollarlabs.io/dollarback-store-credit/widgets-and-storefront/customer-account-blocks.md)
* [Widget map: what shows where](https://help.dollarlabs.io/dollarback-store-credit/widgets-and-storefront/widget-map-what-shows-where.md)
* [How customers spend their credit](https://help.dollarlabs.io/dollarback-store-credit/spending-store-credit-and-rewards/how-customers-spend-their-credit.md)
* [Loyalty tiers overview](https://help.dollarlabs.io/dollarback-store-credit/loyalty-tiers/loyalty-tiers-overview.md)
