Select one of the following pass verticals to learn more about how it can be used.
The Google Pay API for Passes allows you to engage with users through offers. The concepts discussed in this guide should help you better understand the capabilities of saved offers.
The following use cases are available only to the Offer vertical:
- Update passes.
- Offer expiration notification.
- Geofenced notifications.
- Handle expired passes.
- Link to a saved pass.
- Link out from a saved pass.
Update passes
If there are changes to a pass after it's created, use the REST API to deliver those changes to users. If the changes affect only classes, you can also use the Google Pay Merchant Center. Pass updates are an important way to engage with your users.
To update the way passes are displayed, such as when the
logo changes, you only need to
update
or patch
the OfferClass
or use the
Google Pay Merchant Center.
Google propagates this information to all OfferObject
s associated
to the updated OfferClass
. This is the case for all fields defined
at the OfferClass
level.
To update a single pass, such as when the offer expiration changes, you need to
update
or patch
a single OfferObject
. This is the case for all fields defined at
the OfferObject
level.
Sometimes, you might not know when a change happens, or when to trigger an update
or
patch
request. In cases like that, periodically schedule update
or
patch
requests for each and every class and object. You can find all classes of a
particular issuer account if you call the OfferClass
list
method.
You can find all objects of a particular class if you call the OfferObject
list
method.
Offer expiration notification
To remind users to use offers before they expire, a default notification is triggered 48 hours before an offer expires. To trigger a notification, an offer must meet the following criteria:
- It must not have previously triggered an expiration notification on the user’s device.
- It must have a valid expiration
datetime
that's in the future, set invalidTimeInterval.end.date
. - It must have been saved on the user's device for over 12 hours.
- It must not have the writeable field
disableExpirationNotification
set toTrue
. By default, this field is set tofalse
.
The following screenshot shows an example of the default, unmodifiable notification:

- Offer expires (today, tomorrow, in [x] days)
class.title
class.titleImage
The header in the offer expiration notification cannot be customized.
Blackout hours
If the offer expiration notification is set to appear between 10PM and 6AM at the user’s local time, the offer appears either before or after this time period.
Custom offer expiration notification time
You can customize when the Offer
expiration notification appears using the
message.displayInterval.start.date
field on OfferObjects
or
OfferClasses
. If a custom notification time is set, the expiration notification triggers
according to the message.displayInterval.start.date
, instead of the default logic
calculated from validTimeInterval.end.date
. The following is a sample of a customized
time for an expiration notification:
{ “message”: { “messageType”: “expirationNotification”, “displayInterval”: { “start”: { “date”: datetime } } } }
The displayInterval.start.date
sets the time the notification appears. It can be
set up to 30 days prior to the expiration date. If a time span greater than this is specified, the
notification triggers at the 30 day mark. This message doesn't require a header and body field -
if they're included they aren't used.
Geofenced notifications
Google can trigger notifications related to a consumer's saved Object based on the consumer's proximity to a location you've defined.
There are two ways geolocation information is added:
- Geolocation information from Google Maps is used when a Google Pay API for Passes Merchant Center account is created.
- Coordinates can be added to the object or class through the REST API.
For instructions on adding coordinates to objects or classes, see Add geolocation information using the REST API.
Geofencing concepts
Using geolocation information in Google Maps, Google algorithmically determines if the user is physically in the store or area. This detection applies to all classes and objects developed under the Google Pay API for Passes Merchant Center account.
The algorithm considers GPS, Wifi, Bluetooth, movement, dwell time and other factors. When the user is determined to be physically present, a geofenced notification is triggered.
If coordinates are manually specified in the Object
, the geofenced notification is
triggered when they are 150 meters from the coordinates.
Frequency, throttling, and user opt-out of geofenced notifications
At maximum, a user receives up to four notifications per day.
When there are multiple saved objects within the geofence, a single (per Google Pay API for Passes Merchant Center account), unmodifiable notification with a carousel appears. Objects are cyclable within the carousel:

For geofenced notifications to work, the user must enable Updates about your items in the Google Pay app’s notification settings and must have location services turned on for their device.
Add geolocation information using the REST API
You can specify an array of locations (latitudes and longitudes) in your classes or objects. Google checks the user's current geolocation against the list of locations associated with a class or object and notifies the user if they are within 150 meters of one of the locations. The following are code samples showing how to specify locations in your classes or objects:
Resource
{ ... //Class or Object content "locations": [{ "kind": "walletobjects#latLongPoint", "latitude": 37.422087, "longitude": -161446 }, { "kind": "walletobjects#latLongPoint", "latitude": 37.429379, "longitude": -121.12272999999999 }, { "kind": "walletobjects#latLongPoint", "latitude": 37.333646, "longitude": -122.884853 }] }
Java
List<LatLongPoint> locations = new ArrayList<LatLongPoint>(); locations.add(new LatLongPoint().setLatitude(37.422087).setLongitude( -122.161446)); locations.add(new LatLongPoint().setLatitude(37.429379).setLongitude( -121.12272999999999)); locations.add(new LatLongPoint().setLatitude(37.333646).setLongitude( -122.884853)); yourClassOrObject.setLocations(locations);
PHP
$locations = array( array( 'kind' => 'walletobjects#latLongPoint', 'latitude' => 37.442087, 'longitude' => -122.161446 ), array( 'kind' => 'walletobjects#latLongPoint', 'latitude' => 37.429379, 'longitude' => -122.12272999999999 ), array( 'kind' => 'walletobjects#latLongPoint', 'latitude' => 37.333646, 'longitude' => -121.884853 ) );
Python
offer_class_object = { # class or object content 'locations': [{ 'kind': 'walletobjects#latLongPoint', 'latitude': 37.442087, 'longitude': -122.161446 },{ 'kind': 'walletobjects#latLongPoint', 'latitude': 37.429379, 'longitude': -122.12272999999999 },{ 'kind': 'walletobjects#latLongPoint', 'latitude': 37.333646, 'longitude': -121.884853 }] }
Handle expired passes
Under the "Passes" tab of the Google Pay app, there's an "Expired passes" section that contains all archived or inactive passes. A pass is moved to the "Expired passes" section if at least one of the following conditions is true:
-
object.validTimeInterval.end.date
expires. The pass moves to "Expired passes" anytime up to 24 hours afterobject.validTimeInterval.end.date
expired. -
The
object.state
field is marked asExpired
,Inactive
, orCompleted
.
Link to a saved pass
Once a user has a pass saved, reference its objectId
in order to link to the
pass.
Use the following link to reference the pass:
https://pay.google.com/gp/v/object/{<issuerId>}.{<ObjectId>}
The pass can be viewed with the Google Pay app or a web browser.
Link out from a saved Google Pay pass
You can link to your app or website below the header of a saved Google Pay pass. This feature is available for all types of Google Pay passes.
Request access
Request access with the support form for in-store merchants. Keep the following in mind:
- You must share your issuer ID in the form.
- Under Issue type, select "Technical/API Integration."
- Select Link your app or website below the Google Pay pass.
Set the app link on your Google Pay pass
For a given Google Pay pass, define appLinkData
to set the URI of your app or
website. The URI can be any format, but we recommend that you use a
dynamic link.
The format and context of the appLinkData
field can be seen in the following source
code:
{ "id": string, "classId": string, … … … "appLinkData": { "androidAppLinkInfo": { "appLogoImage": { "sourceUri": { "uri": string } }, "title": { "defaultValue": { "language": string, "value": string } }, "description": { "defaultValue": { "language": string, "value": string } }, "appTarget": { "targetUri": { "uri": string, "description": string } } } } … … … }