> ## Documentation Index
> Fetch the complete documentation index at: https://docs.masivo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Add coupons to Apple and Google Wallet

> Create a wallet pass template, enable it on a coupon campaign, and share the claim page.

Customers save a Masivo coupon code in Apple Wallet or Google Wallet. The phone
shows the offer, the code, and a QR or Code 128. Masivo stays the source of
truth for whether the code can still be used.

This flow does not use `@masivo/rn`. Web, native apps, email, and WhatsApp
share the same Storefront endpoints.

## Prerequisites

[Apple and/or Google credentials](https://docs.masivo.ai/guides/settings/wallet-passes.md) saved in
**Settings → Wallet passes**

A coupon campaign with available codesWrite access to Settings and Campaigns

## Create a template

Templates live in **Settings → Wallet passes → Templates**. They are not HTML.
Apple and Google only expose fixed slots. The dashboard preview matches those
slots.

**1. Open Templates**

Go to **Settings → Wallet passes → Templates** and click
**New wallet pass template**.

**2. Set the alias and copy**

**Alias** is internal (for example `KFC 500 points`). On the pass itself:

| Field | Where it shows |
| - | - |
| **Header** | Title next to the logo |
| **Offer label** / **Offer text** | Large value (for example `500 points`) |
| **Description** | Landing page under the title |
| **Code label** | Label above the coupon code |
| **Status label** | Label above Available / Redeemed / Expired |

**3. Pick colors**

Use the color pickers for **Background**, **Foreground** (values), and
**Label**. Colors must be `#RRGGBB`.

**4. Choose the barcode**

Open the **Actions** tab. **QR** or **Code 128** encodes the coupon code.
Stores scan that code at redemption. Optional back-of-pass label and URL
appear on Apple Wallet.

**5. Upload images**

| Image | Role |
| - | - |
| **Logo** | Top-left icon next to the header |
| **Icon** | Thumbnail when Wallet stacks many passes |
| **Illustration** | Artwork on the right of the offer |

Use PNG or JPEG. Prefer a square logo. Apple shows it as a small icon;
the header text is native, not part of the image.

**6. Save**

The templates table shows a scaled preview of the full pass. Hover to
zoom. Open the row to edit.

> [!NOTE]
>
> A pass already saved on a phone does not pick up template edits. The
> customer must delete it from Wallet and tap **Add to Apple Wallet** or
> **Add to Google Wallet** again. You do not need to redeem the code.

## Enable it on a coupon campaign

**1. Open the coupon**

Go to **Campaigns → Coupons** and open the campaign.

**2. Turn on Add to Wallet**

Enable **Allow Add to Wallet** and select the template. Each visitor who
opens the campaign link gets the next unused coupon code. The same
phone keeps that code.

**3. Save the campaign**

Issuing a pass fails until Wallet is enabled and a template is selected.

## Share the pass

Call
[`POST /coupons/wallet-passes`](https://docs.masivo.ai/api-reference/coupons/wallet-passes/post)
once per campaign. The same `claim_url` is returned if you call it again.
Read it later with
[`GET /coupons/wallet-passes`](https://docs.masivo.ai/api-reference/coupons/wallet-passes/get).
Wrap it in a Masivo short link for email or WhatsApp.

Each new visitor who opens the URL receives the next available coupon code.
The same browser (cookie) keeps that code. If that pass was already redeemed,
expired, or revoked, the landing says so instead of issuing a new one. When the pool is empty the
landing says no coupons are left. Coupon redeem rules are unchanged.

| Field | Use |
| - | - |
| `claim_url` | Public `/w/{token}`. Detects the OS and redirects iPhone to Apple Wallet and Android to Google Wallet. Desktop sees both buttons. |

The customer does not need your app installed to use `claim_url`.
`POST /coupons/wallet-passes` stays authenticated. Do not unprotect issue.

On iPhone, tap **Add to Apple Wallet**. On Android, tap **Add to Google Wallet**
while signed into a [demo tester Gmail](https://docs.masivo.ai/guides/settings/wallet-passes.md#add-demo-testers)
if the issuer is still in Demo mode.

## Redeem

[`POST /coupons/redeem`](https://docs.masivo.ai/api-reference/coupons/redeem/post) with the coupon
code and `customer_id`. A pass without a customer is assigned to that customer
on its first redeem. It stays `CLAIMED` while the customer has uses left and
becomes `REDEEMED` at the campaign limit per customer.

After redeem, reverse, expire, or revoke, Masivo updates the pass in Apple
Wallet and Google Wallet.

## Next steps

Full request and response examples:
[Add a coupon to a wallet](https://docs.masivo.ai/api-reference/guides/add-coupon-to-wallet.md).

How statuses work: [Wallet passes](https://docs.masivo.ai/concepts/wallet-passes.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.