Change Message Tutorial
Alerting pass holders when pass content has been changed is only available for Apple Wallet.
When a change message is posted to a user’s device, the screen displays a title and the pass’s icon image along with the notification. The user’s device will not play a sound or vibrate.

The title displayed with a notification is the company name associated with your Wallet account, unless you set a custom change message title for the template.
Each field object on an Apple Wallet pass can include an optional change message value. A change message is the text that appears in an alert that is displayed when a pass field’s value is changed.
The change message includes the escape value %@
, which is replaced when the
field’s value is changed. For example, if you enter the change message
“Gate changed to %@” and you later change the field value to “A64,” the
alert text would be “Gate changed to A64.”
- If you don’t specify a change message, the pass holder isn’t notified when the field value changes.
- Setting a change message will not trigger sending a notification — the notification is triggered when you change the field value.
- When multiple fields with change messages are updated at the same time, we cannot control the processing order. That is handled by Apple.
Add a Change Message Using the Dashboard
- Go to Templates.
- Click anywhere in a template’s row to see its expanded view. If you have only one template in the project, the initial view is expanded.
- Click Edit Design.
- Select a field, click Advanced Options at the bottom of its configuration pane, then check the box for Notify the user when this value changes.
- Enter the text that will appear in the notification, including the placeholder
%@
for the field’s new value.Important A notification will not be triggered if
%@
is not in your change message. - Click Save.
Add a Change Message Using the API
The following is an example of a pass field that includes an optional change
message value using the key changeMessage
. The value of changeMessage
is
the text that will appear in the notification. The placeholder %@
for the
field’s new value is required.
When updating a pass, if the specified value is different than what is currently included on the pass, then the change message will be displayed on the user’s device. The notification, in this case, would be “The value for this field has changed to New text value.”
A notification will not be triggered if %@
is not in your change message.
{
"fields": {
"TextField": {
"changeMessage": "The value for this field has changed to %@",
"value": "New text value",
"label": "Text Field Label"
}
}
}
Set a Custom Title For Change Messages
By default, the title of change message notifications for iOS is the “company name”
associated with your Wallet account. You can set a custom title for
change messages by adding a changeMessageTitle
field to your template. The Default
Value of the field becomes the title of change message notifications.

To set a custom change message title for your template:
- Click Add a Field or Add Another Field. While this field must be on the template, you can place the field anywhere. It is recommended that you add the field to the back of your pass template, so that it is as unobtrusive as possible.
- Set the Field ID to
changeMessageTitle
, select field type Text, and click Next. - Set a Default Value for the field. This value will be the title of change message notifications for the template.
You can represent the field in the API as a changeMessageTitle
object in the fields
object of a template
"fields": {
"changeMessageTitle": {
"value": "Title for change messages",
"fieldType": "back"
}
}
Send Pass Update
Now that you have a change message set, the alerts are handled automatically. After you edit the value of a field in a template and save the changes, you then need to give your passholders the latest version of the pass, via the API or the dashboard.
Publish will only update fields on the back of a pass. If you intend to send pass updates via Publish, add a “Messages” field to back of the pass template, include a change message, and use the field for your change notifications.
Best Practices for Change Messages
Message Length: Keep your change messages short. The notification will be truncated if it’s too long, just like other notifications.
Spam: Do not change field values frequently. Multiple alerts will likely lead to users removing your pass.
Latest Message: If you plan on sending promotional or marketing messaging to your users, consider including a field on the back of a pass that always displays the latest message. This allows the message to persist even after a user has dismissed the notification. See the note in Send Pass Update.
Categories