API reference

The pass object

Every field of a pass, with its limits and where it shows.

The pass

What you send to create or replace a pass. It needs organizationName, and logoText or primaryFields. A field you leave out is left off the pass. 30 fields. Choose a field's name to see where it shows.

AAcme

Tier

Gold

Points

120

Member

Priya Shah

Since

2024

MEMBER-1042

ⓘ Latest message and more on the back

An example pass. Wallet lays out each kind a little differently.

styleone of: generic, loyalty, coupon, event

The kind of pass. It sets the layout and how large the main field is. Left out, it follows from the images: a strip image makes a store card.

string· up to 1,024 characters· or null

What the barcode holds. Null or empty means no barcode.

one of: QR, PDF417, Aztec, Code128

The barcode's kind. Needed when there's a barcodeValue.

string· up to 128 characters

Text under the barcode. Left out, it's the value; empty hides it.

string· up to 64 characters

The name beside the logo, top left.

descriptionstring· up to 128 characters

The title of the pass's details page in Apple Wallet, read aloud by VoiceOver, and the line under the pass name on its install page. Left out, the logo text.

organizationNamestringrequired· 1 to 64 characters

Your business's name: on the lock screen, the share sheet and the pass's details.

array of field objects· up to 10

Top right, visible while the pass is stacked in Wallet. Keep it to one short value.

array of field objects· up to 10

The main value, shown large: points, a balance, an event's name.

array of field objects· up to 10

The row under the main value.

array of field objects· up to 10

On the back of the Apple pass and in the Google pass's details: terms, contact details, links.

array of field objects· up to 2

The bottom row: the poster layout's footer, and the auxiliary row elsewhere.

array of field objects· up to 4

The row under that, on the classic layouts.

locationsarray of location objects· up to 10

Places where the pass appears on the lock screen when the holder is near.

featuredActionsarray of featured action objects· up to 2

Buttons on the pass, such as call or book: up to 2.

sharingProhibitedboolean· default true

Hides Apple Wallet's share button.

one of: dark, blue, green, red, purple, orange

A ready-made background colour.

hex colour· like #1f3b2d

Your own background colour. Text colours are chosen to stay readable on it.

expirationDayswhole number· 1 to 3,650

Expires this many days after it's issued.

expiresAtdate and time (ISO 8601)

Expires at this moment, at most 10 years ahead. It wins over expirationDays.

string

An image: the reference from Upload an image with type=logo. Top left, beside the logo text. Upload 660 × 660 pixels, or that shape.

string

An image: the reference from Upload an image with type=wideLogo. Google Wallet only: a wide logo, shown top left in place of the square one. Upload 1280 × 400 pixels, or that shape.

thumbnailURLstring

An image: the reference from Upload an image with type=thumbnail. Beside the fields, on event tickets and generic passes. Upload 270 × 270 pixels, or that shape.

string

An image: the reference from Upload an image with type=strip. Behind the main value (it makes a store card), and Google Wallet's hero image when there's no googleHeroURL. Upload 1125 × 369 pixels, or that shape.

backgroundURLstring

An image: the reference from Upload an image with type=background. Apple Wallet only: the poster layout's artwork. Upload 1074 × 1344 pixels, or that shape.

iconURLstring

An image: the reference from Upload an image with type=icon. Shown in notifications and on the lock screen. Upload 87 × 87 pixels, or that shape.

googleHeroURLstring

An image: the reference from Upload an image with type=googleHero. Google Wallet only: the hero image, across the card under its fields. Google recommends a nearly square one; without it, Google Wallet shows the strip. Upload 1032 × 812 pixels, or that shape.

metadataobject

Your own data, kept with the pass and searchable. Never shown on it.

externalIdstring· up to 256 characters

Your own ID for the pass, such as a member number. Unique in the workspace; find the pass by it.

object

The Latest message field on the back. Every pass has one; it's normally set by sending a notification. Leave it out to keep it.

Field object

One label and value on the pass, in any of the field rows. 4 fields.

keystringrequired· 1 to 64 characters

Its name in your system, unique on the pass. Keep it the same across updates.

labelstring· up to 64 characters

The small heading above the value.

valuestringrequired· up to 1,024 characters

What it shows.

changeMessagestring· up to 128 characters

Shown as a notification when an update changes the value. %@ stands for the new value: "You now have %@ points".

Location object

A place where the pass surfaces on the lock screen. 4 fields.

latitudenumberrequired· -90 to 90

In degrees.

longitudenumberrequired· -180 to 180

In degrees.

altitudenumber

In metres.

relevantTextstring· up to 128 characters

The lock-screen text, such as "Your card is ready at the till".

Featured action object

A button on the pass. 4 fields.

idstringrequired· 1 to 64 characters

Its name in your system, unique on the pass.

typeone of: viewSchedule, watchTrailer, listenToMusic, call, place, addToBalance, order, shop, membershipBenefits, bookAppointment, bookCar, bookFlight, bookStay, viewOffersRewardsrequired

What it does. Apple hides every action if one type isn't one of these.

urlstring

Where it goes: HTTPS, or tel: for call. Required for every type but place, where it's optional and only Google Wallet uses it (a Google Maps link opens the Maps app on Android).

placeIdentifierstring

place only, and required there: the venue's Apple Maps Place ID, such as I7C250D2CDCB364A, from Apple's Place ID Lookup. iPhones open the place in Maps.

These tables are read from the schemas the API checks with, so they always match it. The same is in the OpenAPI document.