Lifecycle & messaging

Change message

The per-field template in an Apple Wallet pass that turns a value change into a lock screen notification, such as announcing a new points balance.

A change message is a small template attached to a field in pass.json, written as changeMessage in the file. When that field's value changes in a push update, Apple Wallet shows the message on the lock screen with the new value substituted in. A points field with the template "You now have %@ points" produces a lock screen line reading "You now have 1,250 points" the moment the balance updates.

The elegance is that the notification is a property of the pass, not a separate messaging system. There is no app requesting notification permission and no push campaign to build; keeping the pass truthful is what generates the message. That makes change messages the quietest kind of loyalty communication: they only ever say something that just became true for that member.

Each field carries its own template, so a program chooses which changes speak and which stay silent. A balance ticking up on every purchase might update silently, while a tier field announces "Welcome to Gold." Wallets ultimately decide how notifications are presented and coalesced, so treat the message as a courtesy line, not a guaranteed impression.

Google Wallet approaches the same need differently, with messages attached to pass objects rather than field-level templates. A wallet platform abstracts the two, and the broader craft, what to announce and how often, is covered under lock screen messages.

How updates and push work
Next step

See what this looks like on a pass.

The definition is the short version. The next pages show it on the terminals merchants already run, and the merchants running it.