How live pass updates work

A wallet pass looks like a plastic card, but it behaves more like a small document that Stow Cards can replace. An Apple Wallet pass carries the address of the Stow Cards update service and a private token, so the iPhone knows where to ask for a newer version and Stow Cards knows the request is genuine. A Google Wallet card lives on Google’s servers, where Stow Cards can edit it. Everything below builds on those two facts.

What starts an update

Anything that changes what the pass shows:

• Points and stamps. Staff add them with the Stow Cards Merchant app at the till or from the console, or your checkout adds them through the API. All three use the same points call.
• Rewards. Redeeming a full stamp card updates the pass with the new count.
• Messages. A campaign to all members or a segment (other than an email campaign), or a single update sent from a member’s page in the console, changes the “Latest update” field on an Apple pass and shows as a message on a Google Wallet card.

Tiers follow the balance. When an adjustment carries a member past a tier’s target, the tier changes in the same step, and the tier-upgrade message goes out instead of the usual one.

Step 1: the change is recorded once

Stow Cards writes the new balance in a single database operation. If two staff members add points to the same customer at the same moment, both count, and a balance never drops below zero.

Requests from the scanner app and the API can carry an idempotency key, so a request that is sent again after a dropped connection doesn’t add the points twice.

Before it changes a balance, Stow Cards also notes that the pass needs updating. If the update can’t reach the pass service, a background job tries again, waiting a little longer each time, so a short outage doesn’t leave a customer looking at an old number.

Step 2: the pass is rebuilt

The pass service builds a fresh Apple Wallet pass from the member’s current values and your program’s design. It keeps the same private token, so phones that already hold the pass accept the new version, and it stamps the pass with a new update marker.

This is also where your message is attached. Apple Wallet raises a lock-screen alert only when a field’s value changes, so Stow Cards puts your text, exactly as you wrote it, in a “Latest update” field on the back of the pass. Write “Thanks for visiting! 290 points” and that is what the customer sees; to show the new balance, put {after} in the template.

You change the number once. The pass, the push and the message follow from it.

Step 3: Apple Wallet fetches the new pass

When a customer adds the pass on an iPhone, the phone registers with Stow Cards for updates. That registration is how the console knows the pass is installed, and it gives Stow Cards a push address for that device.

After a rebuild, Stow Cards sends an empty notification through Apple’s push service to every device registered for the pass. It carries no balance and no personal details; it only tells Wallet to check in. Wallet then asks Stow Cards which of its passes have changed, downloads the new version, swaps it in and shows your message on the lock screen.

If a customer deletes the pass, the phone unregisters and the pushes stop. A customer can also turn off notifications for your pass in Wallet. The pass still updates; they just don’t see the message.

Step 4: Google Wallet changes in place

Google Wallet works the other way round. Because the card lives on Google’s servers, Stow Cards edits it directly with the new balance and your message, and Google syncs the card to the customer’s phone.

Google tells Stow Cards when a customer saves the card or removes it, so only saved cards are updated. A customer who chose Apple Wallet, or never tapped the Google Wallet button, doesn’t cause a wasted call or an update entry in the console for a card that isn’t there.

What you control

• Whether a change notifies. In the Pass Designer’s Notify step, “Send a push notification on every change” is on unless you turn it off. With it off, the Google Wallet card still changes in place without a message, and the Apple pass is rebuilt without a push, so an iPhone picks up the new value the next time Wallet refreshes the pass.
• The message. The same step holds the message template, with placeholders such as {label}, {before}, {after}, {delta}, {goal}, {programName} and {businessName} filled in for each customer. Stamp cards can have a separate message for a completed card, and tiered programs a tier-upgrade message.
• Your house wording. The console’s Wallet messages page holds your default messages, used when a program doesn’t set its own.
• A one-off message. On a member’s screen in the scanner app, staff can type their own message; if they leave it empty, the app sends the change itself, such as +10 points. An API call can send its own message too. Either one replaces the template, and any tier-upgrade message, for that update.

Checking that it worked

Each member’s page in the console has an activity timeline with a line for every step: the pass updated, the push delivered to each iPhone, the Google Wallet card updated, and each device that installed the pass. You can export the timeline as a CSV file.

If you connect through the API, the points call reports how many iPhones accepted the update push, and the pass.updated webhook fires after each pass update. The developer docs cover both.

The short version

Staff change the balance once. Stow Cards rebuilds the pass, nudges every iPhone that holds it, edits the Google Wallet card, and tries again if something is briefly down. Your customer sees the new balance, and your message, on a phone they already carry.