> 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 every time they earn or spend, 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](/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.

### 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 |                       |

{% 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                   |
| `{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}.`

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.

Two consequences on Apple:

* **`{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 default *"Your balance is now …"*. Write the earned message around `{balance}` if you want your own wording on iPhone.
* `{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. The pass is then offered to customers.

## What the pass shows

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

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.

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 updates the pass balance on both platforms. 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 it drops the notification silently if the message doesn't include the balance. 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](/dollarback-store-credit/widgets-and-storefront/customer-account-blocks.md).
* 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](/dollarback-store-credit/widgets-and-storefront/customer-account-blocks.md)
* [Widget map: what shows where](/dollarback-store-credit/widgets-and-storefront/widget-map-what-shows-where.md)
* [How customers spend their credit](/dollarback-store-credit/spending-store-credit-and-rewards/how-customers-spend-their-credit.md)
* [Loyalty tiers overview](/dollarback-store-credit/loyalty-tiers/loyalty-tiers-overview.md)