Twelve wallet-pass limits worth knowing before you design one

The card face is a template, not a canvas

A wallet pass is not a web page. Apple Wallet and Google Wallet each hand you a fixed template: a handful of text slots, a few image slots at exact pixel sizes, and a notification channel the phone controls rather than you. Every limit below is a platform limit, not a vendor limit, so no loyalty product can sell you around them.

That includes ours, and it includes Niqati and Btaqa, who ship wallet passes too and design inside the same caps. What differs between products is what gets rendered in the space Apple and Google allow.

Apple's store-card layout gives you a header row, one primary slot, and a row of secondary and auxiliary values. Apple caps each region in the single digits. The real limit is lower: on a card about 375 points wide, four or five short values is all that reads cleanly.

Waya's stamp card spends that budget deliberately. One header value carries rewards earned. There is no primary field at all, because the stamp strip is the hero image, and two auxiliary values hold the holder's first name and the reward.

Text truncates. It does not wrap. A label like VISITS UNTIL YOUR NEXT FREE COFFEE gets clipped after two words on a real iPhone, and Arabic labels run out of room just as fast as English ones. Write labels at 12 to 16 characters, then check them on a physical phone rather than in a design tool.

Images have exact sizes, and every byte ships twice

Apple wants the strip image at 375 x 123 pixels at 1x, 750 x 246 at 2x, and 1125 x 369 at 3x. The icon needs 29, 58, and 87 pixel squares, and that icon is not decoration: a pass missing it fails validation and will not install. Those are the sizes Waya renders server-side for every card, which is why a merchant who uploads a 4,000-pixel logo still gets a crisp pass.

One trap costs people a day of debugging. Apple's store-card style renders strip.png and ignores thumbnail.png completely, because thumbnails only apply to the generic and event-ticket styles. Pack an image as a thumbnail on a loyalty card and it silently never appears, with nothing in the build to warn you.

Weight matters more than people expect. The .pkpass file is downloaded when the customer installs the card, and again on every update, often on a phone with two bars of signal in a mall basement. Keep the whole bundle in the low hundreds of kilobytes.

Google Wallet uses different geometry: a hero image and a circular logo rather than a strip. An asset that looks right in Apple Wallet often crops badly on Android. Design the logo so it survives a circular mask, and keep words away from the edges of a hero image.

No HTML, one kind of link, and four barcode formats

You cannot style the back of a pass. Apple's back fields are plain text: no bold, no bullet lists, no images, no CSS. There is exactly one exception, an attributed value that accepts a single HTML anchor tag, which is how the Maps and website rows on a Waya pass become tappable. If your terms and conditions rely on formatting to be readable, rewrite them as short lines.

Google Wallet works the same way in spirit. Text modules are plain strings, links live in their own module, and anything resembling markup is stripped or rejected.

Barcodes are a closed list. Apple signs four formats: QR, PDF417, Aztec, and Code 128. Google Wallet's loyalty objects cover those plus a few 1D retail formats. Waya issues QR only, because it is the one format every phone camera and every cheap counter scanner reads with no configuration.

Here is the detail that bites. The barcode payload carries a text encoding, and the standard choice, ISO-8859-1, cannot represent Arabic characters at all. Put a customer's Arabic name in the payload and you get a corrupt scan or a rejected pass. Encode an identifier instead, and keep human-readable text in the alternate-text line printed under the code.

A notification only fires when the pass actually changed

This is the limit that surprises everyone. Apple does not send your message. It sends the phone a silent push that means fetch this pass again. The lock-screen banner appears only if the refetched pass differs from the installed one, and only for fields you marked with a change message.

The consequence is blunt: send identical text twice and the second send is silent. Waya writes each customer's latest message into a back field flagged with a change message, so the content genuinely differs on every send. It also means the wording you choose matters more than the send button you press.

Timing is not yours either. The device decides when to fetch, and a low battery, Low Data Mode, or a phone locked in a pocket can stretch that from seconds to hours. On the Android side, Waya appends a message to the loyalty object and asks Google to notify. Google throttles notify-type messages per object, so pushing the same object repeatedly in one day tends to land later messages as quiet text.

None of this is SMS. There is no per-message telecom fee and no customer number handed to a third-party messaging app, but the flip side is real: you can only reach someone who installed the pass. If a customer replaced their phone or deleted the card, Apple returns a 410 on that push token, which is the platform telling you the address is dead. Waya marks the registration and clears it nightly, which keeps your delivered numbers honest.

Messages are counted when you send, not when they land

On Waya the metered thing is wallet messages, not customers. The free plan includes 100 messages a month and stops there. Growth at 85 SAR a month includes 5,000, and Premium at 149 SAR a month is unmetered on messages. Whatever platform you use, ask how the meter runs before you plan a campaign calendar.

On Waya it runs per recipient, charged when the campaign is accepted, before any phone is consulted. Target 300 people and it costs 300 messages, even if a dozen of those devices have dead push tokens. That is deliberate, because the alternative is a bill that changes after the fact, but it means an uncleaned audience costs real quota.

The practical rule is to send fewer, larger messages. Four well-targeted sends a month beat twenty sent to everyone, and four sends of 25 recipients each fits inside the free plan's 100 with nothing to spare. Free also stops at 100 enrolled customers, and the customers you already have keep their cards and keep collecting stamps.

Geofences, deletion, and the phone switch

Apple allows 10 locations per pass. Waya emits up to 10 branch coordinates with a default radius of 150 meters, and that radius is advisory: iOS decides whether your card is relevant enough to surface. It is a lock-screen suggestion, not a push you can schedule, and it reads the coordinates saved on the Branches screen rather than the address text printed on the card. Those are two different fields, and mixing them up is the most common setup mistake we see.

Deletion is quiet and one-way. When a customer removes the pass, the device unregisters and you lose the channel to that phone with no notice beyond that unregister call. There is no reinstall you can trigger remotely, so the customer has to scan your QR code again. Their visit history stays in your dashboard, which is the difference between losing a channel and losing data.

New phones are the common case, and the answer is better than most people assume, because stamps live on the server and not inside the pass. An iPhone restored from a backup normally brings its passes back and re-registers with a fresh push token. A brand-new phone with no restore, or a switch from iPhone to Android, loses the pass. The customer then rescans your QR code and enters the same mobile number, and the same card returns with every stamp intact.

Google Wallet passes follow the Google account, so a new Android phone signed into the same account already has them. Worth telling your cashier: an iPhone customer with a new handset may need to rescan, an Android customer usually does not.

Two things you cannot change after issue: the pass type identifier that ties an Apple pass to its signing certificate, and the object identity on Google's side. Colors, text, images, and stamp counts all update over the air. Swap the underlying identity and every installed card is orphaned.

Let the Apple signing certificate lapse and you can neither mint new passes nor push updates, because an update is just a freshly signed pass. The cards already on phones keep showing whatever they last received. If you run this yourself, put the certificate expiry in a calendar. If you use a platform, that expiry is their problem, which is most of the honest argument for using one.

Waya's free plan covers up to 100 customers, 100 messages a month, and one stamp card, with no credit card. The limits above belong to Apple and Google, so knowing them before you design saves you the redesign.