Designing a pass

A pass is one JSON object: the pass object lists every field. We turn it into an Apple Wallet pass and a Google Wallet pass. Each wallet lays the same content out in its own way, so design for the content, not the pixels. The dashboard's editor shows both side by side while you work.

Choose a style

style sets the layout, and how large the main value is:

Left out, it follows from the images: a strip image makes a store card, and otherwise it's generic.

Fill the rows

Each row holds field objects: a key, a label and a value.

• headerFields, top right: the only row you can see while the pass is stacked in Wallet. Up to 3; keep it to one short value, as narrow phones drop what doesn't fit.
• primaryFields, the main value, shown large: 1.
• secondaryFields and auxiliaryFields, the rows beneath: up to 4 each. On store cards and coupons, and generic passes with a square barcode, the two rows share 4 between them.
• backFields, on the back of the Apple pass and in the Google pass's details: terms, opening hours, links. Up to 10.

A pass with more fields than its layout can show is refused with a validation_error, rather than Wallet quietly dropping them.

Keep each field's key the same from one update to the next: it's how Wallet knows which value changed. Give a field a changeMessage, such as "You now have %@ points", and holders are notified when its value changes (%@ is the new value).

Add a barcode

{ "barcodeValue": "MEMBER-1042", "barcodeFormat": "QR", "barcodeAltText": "1042" }

barcodeFormat is QR, PDF417, Aztec or Code128. The text under the barcode is barcodeAltText: left out, it's the value, and "" hides it.

Colours

Choose a colorPreset (dark, blue, green, red, purple or orange), or your own color as hex, such as #1f3b2d. Label and value colours are chosen for you, so text stays readable on it.

Images

Upload each image once with Upload an image, then put its reference in the pass:

{ "logoURL": "asset:asset_k3m9q2w7x4n8p1r6" }

Each type has its own shape, and an upload is resized to it, so crop to that shape first. These sizes are sharp on every screen:

Google Wallet shows googleHeroURL across the card, under its fields. Google's brand guidelines recommend a nearly square hero image (1032 × 812) and advise against thin ones, so add one rather than relying on the strip, which Google Wallet shows in its place.

Apple Wallet shows each image only on the layouts that have it: a strip on store cards, coupons and event tickets, and a thumbnail on generic passes and event tickets. An event ticket with a strip can't also have a thumbnail or a background: that's refused.

A background gives a pass Apple's poster layout on iPhones that have it (iOS 27 and later). On an event ticket, older iPhones show it as the classic ticket's blurred background, or show the ticket's strip instead if it has one. The poster shows up to 4 primary fields over the artwork, with one header and one footer field (footerFields); the rest move to the pass's details. Older iPhones show the classic layout.

Where and when

• locations: up to 10 places where the pass appears on the lock screen when the holder is near, with relevantText to say why.
• featuredActions: up to 2 buttons on the pass, such as call with a tel: link, or order with an HTTPS one. A place button takes the venue's Apple Maps Place ID as placeIdentifier (find it with Apple's Place ID Lookup), and optionally a url for Google Wallet.
• expiresAt or expirationDays: when the pass expires. Wallet marks it as expired then.
• sharingProhibited hides Apple Wallet's share button. It's on unless you turn it off.

Your own data

externalId is your ID for the pass, such as a member number: unique in the workspace, and you can find the pass by it. metadata is anything else you want kept with the pass and searchable; neither is shown on it.

The same content, two wallets

Google Wallet shows the first primary field at the top, the other rows as rows, and the back fields in its details. relevantText, the poster layout and the thumbnail are Apple's alone; the wide logo and googleHeroURL are Google's. Everything else appears in both.

To design a pass once and issue it to many people, each with their own values, make it a template.