Wallet passes
Last updated
A wallet pass is a digital loyalty card your customers add to Apple Wallet or Google Wallet — no app required. It shows live loyalty data such as their points balance, referral code, or membership, and Toki updates it on their phone whenever you change the design or their data changes. You can run several passes at once, for example a different design for each membership tier.
Before you start
Wallet passes are included in Toki's paid plans. On the free plan, the Wallet Passes page shows the note "This option is available with one of our paid plans" and the create button stays inactive until you upgrade. Open Billing to compare plans.
How customers add the pass
Customers add the pass from your on-site wallet. The Card Block, a loyalty card you can add to the screens of your wallet in Design, shows an Add to Apple Wallet button and an Add to Google Wallet button. On an iPhone, the Apple button hands the pass to Apple Wallet; on a computer or an Android phone, it shows a QR code to scan with an iPhone instead. The same buttons appear on the Download an Apple pass activity, which can reward customers for adding the pass, and on the refer-a-friend activity.
Customers can also add the pass right after they order, from the Wallet Pass block on Shopify's Thank you page, which you add as described in Install modules on your storefront.
The buttons show only for customers who match an active pass. If you'd rather hide them on the loyalty card, open Design, edit the Wallet module, and in its Card Block turn off Show Add Apple Pass Button or Show Add Google Pass Button. The QR code and the Apple download links open a short download page that you can style with the Apple Pass Download Page module in Design.
Toki also shares each customer's personal download links with your
connected integrations, such as Klaviyo, as the customer properties
toki_apple_download_link and toki_google_download_link, so you can add
them to your own emails and texts. Each link belongs to one customer, works
without signing in, and doesn't expire, so use it in messages to that
customer, for example as the link of a button in a Klaviyo email, where you set the button's link to {{ person|lookup:'toki_apple_download_link' }}. A pass
added from either link counts for your Download an Apple pass activity
too.
To offer the pass on a page of your store, such as a landing page, add a
button that links to #toki-open?toki-owp=/home/activity/ followed by the
ID of your Download an Apple pass activity. To find the ID, open the
activity in Toki: it's the last part of the address in your browser's address
bar. A click opens the wallet on
that activity and its add-to-wallet buttons. A customer who has already
completed the activity sees "Thank you! Your activity has been completed."
instead, and customers who aren't signed in see the wallet's sign-in screen.
The link needs your wallet on the page: with the Toki Wallet app embed
on, that's every page of your online store, including pages where you hide
the wallet's launcher with Pages to exclude in the Wallet module.
Find your wallet passes
- In the merchant portal, open Wallet Passes.
Passes are grouped under Active Passes and Draft Passes. Each card shows a small preview of the pass, its name (the membership tier it belongs to, or Default), and the shop it applies to. Click Edit on a card to open it.
If you delete a membership tier that had its own pass, that pass is labeled Membership deleted. Open it to pick another membership, or delete it.
Create a pass
- Open Wallet Passes and click New. If you have no passes yet, click Create new pass.
- Set the pass basics: Membership, Status, and Shop (see below).
- Design the card. The preview on the right updates as you go. Switch between the Apple and Google tabs to see the pass in each wallet.
- Click Save in the bar at the top. Discard reverts your changes.
New passes start as Draft, so you can take your time with the design. Your first pass comes with a ready-made design that shows the store credit balance in the header and a referral QR code. Every pass after that starts from the design of your most recent default pass, so you only change what's different.
Pass basics
| Field | What it does |
|---|---|
| Membership | Leave as Default for the pass every customer gets. Pick a membership tier to design a pass just for members of that tier. |
| Status | Active passes are delivered to customers. Draft passes are visible only to you. |
| Shop | Leave as All shops, or pick one shop if you run several. |
Members of a tier with its own pass get that pass. Everyone else — and members of tiers without their own pass — gets your default pass. See Passes for membership tiers and shops for the details.
When more than one active pass matches a customer, a tier pass comes before a default pass, and a pass made for the customer's shop comes before one made for all shops. A member of several tiers that each have a pass gets the pass of the tier that comes last in the order you set with Reorder on the Memberships page.
Design your pass
The design form is split into sections. Some settings apply to Apple Wallet only (Icon Image, Colors, and Locations).
Card Header
| Field | What it does |
|---|---|
| Header type | What the top-right corner of the pass shows. See the options below. |
| Store credit | Appears when the header shows a balance and you run more than one store credit. Pick which balance to show. |
| Logo | Shown in the header of the pass. |
| Icon Image | Used for notifications on Apple devices. Apple caches icons on the phone, so a new icon can take a while to appear. |
The Header type options are also available for the two secondary fields:
| Option | What the pass shows |
|---|---|
| None | Nothing. |
| Store Credit | The customer's balance in your store credit, for example "1,200 Points". |
| Your store currency (for example USD) | The same balance in your store currency. |
| Referral | The customer's referral code. |
| Member Number | The customer's member number. |
| Member Name | The customer's name. |
| Member Since | The date the customer joined. |
| Points Expiry | When the customer's points expire. |
| Paid Membership Expiry Date | When the customer's paid membership ends. |
| Paid Membership Name and Period | The name and billing period of the customer's paid membership. |
| Membership | The customer's membership tier. Available when the pass is tied to a membership. |
| Custom | Fixed text you type in: a Label and a Value. |
Card Body
| Field | What it does |
|---|---|
| Title | The card's title text. |
| Background Color | The card's background color. |
| Stamps Type | Show a background image, or turn the card into a punch card. See below. |
| Background Image | The image across the body of the card. Shown when Stamps Type is None. |
A punch card shows stamps that fill in as the customer makes progress. The pass updates automatically, so customers see their progress right in their wallet.
| Stamps Type | What it does |
|---|---|
| None (use background image) | Shows your Background Image instead of stamps. |
| Challenge | Tracks a challenge you select, one activity at a time: one stamp for each completion that activity asks for. Set Stamps Per Row and upload a Default Punch Image, used for activities that have no icon of their own. See Punch cards on wallet passes. |
| Balance | Turns a store credit balance into stamps. Pick the Balance, set Points Per Stamp (for example 200 points = 1 stamp), Maximum Stamps (up to 10), and Stamps Per Row, then upload a Stamp Image. |
Secondary Field
Secondary Field 1 and Secondary Field 2 sit below the card body and
use the same options as Header type. Date Format controls how dates
such as Member Since are written, for example yyyy.MM.dd.
Colors
On the Apple tab you can set Font Color and Foreground Color, the text colors on the Apple Wallet pass. Check the preview to see what each one changes.
QR Code
| Option | What the code contains |
|---|---|
| None | No QR code. |
| Referral | The customer's refer-a-friend link. Friends scan it to use the referral. |
| Personal | A private code that identifies the customer, for example when you scan it at the point of sale. |
Turn on QR Code Alt Text to show a short line under the code, such as "Give $5 Get $5". When any field on the pass uses Referral, a Referral Activity field appears so you can choose which refer-a-friend activity the pass uses.
Locations
Send a notification to the customer's phone when they are near your store. Location notifications are available on Apple Wallet passes.
- Click Add Location.
- Enter the Relevant Text — the text shown in the notification.
- Enter the Latitude and Longitude of the location.
Add as many locations as you have stores. Use the trash icon next to a location to remove it.
Back Fields
Back fields add extra information to the pass, such as program terms, a support email, or a link to your store.
- Click Add Field.
- Choose the Type: Text or Link.
- Enter a Label and a Value. For a link, also enter the URL.
Keep passes up to date
Every time you save a pass, Toki pushes the new design to every customer who has it in their wallet. Balances, codes, and stamps update on their own as customers earn and spend — you don't need to do anything.
Delete a pass
- Open Wallet Passes and click Edit on the pass.
- Click Delete in the top-right corner.
- In the Confirm deletion dialog, click Delete.
Toki then updates the passes on customers' phones. Customers who had a tier-specific pass move to the next pass that matches them, for example your default pass.
If no active pass matches a customer anymore, for example because you set your only pass to Draft, the pass already on their phone stays as it was last updated, and the add-to-wallet buttons are hidden in your on-site wallet until an active pass matches them again.
Additional settings
Once you have at least one pass, the Additional Settings card appears at the bottom of the Wallet Passes page.
| Setting | What it does |
|---|---|
| Allow POS authentication with referral code | Lets customers identify themselves at your point of sale with their referral code. Referral codes are public, so this is less secure than other ways of identifying customers. |
Click Save in the bar at the top to apply the change.