Use cases

This guide outlines the following specific ways that you can use the Google Pay API for Passes to engage with your customers for the Loyalty vertical:

Update points or monetary balance

Updating the loyalty card points balance is an important way to engage with your customer.

There are different forms of loyalty balances:

  • String
  • Int
  • Double
  • Money

The property loyaltyPoints.balance and secondaryLoyaltyPoints.balance should only populate one of the forms above.

Any update should begin with a GET request to retrieve the LoyaltyObject. This ensures that the latest version of the object is used. To save the updated object, make a PUT request.

The following REST URIs are used to GET an object and to UPDATE an object:


The following code samples provide examples of how to update an object in different languages:


// Get the specific Loyalty Object
LoyaltyObject obj = client.loyaltyobject().get("2945482443380251551.ExampleObject1").execute();
// Update points
// Update the Loyalty Object
LoyaltyObject returnObj = client.loyaltyobject().update(obj.getId(), obj).execute();


// Get the specific Loyalty Object
Google_LoyaltyObject loyaltyObj = $service->loyaltyobject->get('2945482443380251551.ExampleObject1');
// Update the points
// Update the Loyalty Object
Google_LoyaltyObject loyaltyObj = $service->loyaltyobject->update('2945482443380251551.ExampleObject1',loyaltyObj);


# Get the specific Loyalty Object
loyalty_object = service.loyaltyobject().get(resourceId='2945482443380251551.ExampleObject1')
# Update the points
loyalty_object['points'] = points
# Update the Loyalty Object
api_request = service.loyaltyobject().update(resourceId='2945482443380251551.ExampleObject1',body=loyalty_object)
api_response = api_request.execute()

Save in the Google Pay app

Users can add a loyalty card to their Google Pay app by either scanning or manually adding the loyalty card details. The Google Pay API for Passes creates a LoyaltyObject that doesn't reference a LoyaltyClass you've previously defined. No action is required on your part to create the new object or class.

Loyalty linked offers

Loyalty linked offers allow existing offers to appear within the loyalty card view, making relevant content easier for the user to discover. The writable list field linkedOfferIds in a LoyaltyObject indicates which offers are associated with the loyalty card. The existing offers can be linked to a loyalty card using the REST calls insert, update, or modifyLinkedOfferObjects.

Creating the offer before linking

To create a loyalty linked offer, the offer classes and objects linked to the loyalty card must already be created. To learn more about creating offers, see Offers. Unlike standalone offers, loyalty linked offers do not require a user to explicitly save the offer. The id field found in the offer object is used to point to the object from the loyalty card.

Link offers to a loyalty card

A loyalty card can have offers linked to it upon its creation using the insert call, as well as when it is updated. A new REST call is also available specifically for changing the offers linked to a loyalty card.

Linking an offer when a loyalty card is created

Offers can be linked to a loyalty card upon creation of the loyalty card. LoyaltyObjects are inserted by making a POST request to the following REST URI:

The field linkedOfferIds can be written with the rest of the LoyaltyObject, using the established format:

  "kind": "walletobjects#loyaltyObject",
  "id": "2945482443380251551.ExampleObject1",
  "classId": "2945482443380251551.ExampleClass1",
  "linkedOfferIds": [
  "2945482443380251551.OfferObject1", "2945482443380251551.OfferObject2"

Linking an offer to an existing loyalty card

Alternatively, you can modify the offers linked to a loyalty card even after its creation. This can be done with an update call or with a new endpoint, modifyLinkedOfferObjects, created specifically to support linking and removing offers to the loyalty card.

You can update an existing LoyaltyObject by making a PUT request to the following address:

The modifyLinkedOfferObjects method is unique to the loyalty class, and sends a POST request to the following address:

More information on using the modifylinkedofferobjects call can be found here.

Its request body has the following format:

  "linkedOfferObjectIds" {
    "addLinkedOfferObjectIds": [
      "2945482443380251551.OfferObject1", "2945482443380251551.OfferObject2"
    "removeLinkedOfferObjectIds": [
      "2945482443380251551.OfferObject3", "2945482443380251551.OfferObject4"

Remove linked offers from a loyalty card

If the field linkedOfferIds is written to during an update call for the LoyaltyObject, the new offers included in this call will overwrite any existing ones. In addition, an offer can be removed using the removeLinkedOfferObjectIds field in the modifylinkedofferobjects call.

Additionally, the linked offers are removed from the loyalty card display by updating the object.state property of the linked offer object to completed. Finally, the linked offers are automatically removed from the display once the set on the linked offer passes. See reference API.

Designing loyalty cards with loyalty linked offers

A loyalty card with offers linked to it has a different template from the typical loyalty card, as shown below.

Google Pay API for Passes Loyalty Linked template
  1. class.programLogo
  2. class.issuerName
  3. class.programName
  4. class.heroImage
  5. object.loyaltyPoints.pointsLabel
  6. object.loyaltyPoints.balance
  7. object.barcode.type


  8. object.accountId
  9. class.hexBackgroundColor
  10. offerClass.heroImage
  11. offerClass.title
  12. offerObject.validTimeInterval.end
  13. class.accountNameLabel
  14. object.accountName
  15. class.accountIdLabel
  16. object.accountId
  17. *.imageModulesData.mainImage
  18. *.messages[0].header
  19. *.messages[0].body
  20. *.textModulesData.header
  21. *.textModulesData.body
  22. *.infoModuleData.labelValueRows[0].columns[0].label
  23. *.infoModuleData.labelValueRows[0].columns[0].value
  24. *.linksModuleData.uris[2]
  25. *.linksModuleData.uris[0]
  26. *.linksModuleData.uris[1]

The loyalty linked offer also takes a different template, as shown below.

Google Pay API for Passes Loyalty Linked template
  1. class.heroImage
  2. object.barcode.type
  3. object.barcode.alternateText
  4. class.title
  5. class.details
  6. object.validTimeInterval.end
  7. class.finePrint

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:

  1. Geolocation information from Google Maps is used when a Google Pay API for Passes Merchant Center account is created.
  2. 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:


  ... //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


List<LatLongPoint> locations = new ArrayList<LatLongPoint>();
locations.add(new LatLongPoint().setLatitude(37.422087).setLongitude(
locations.add(new LatLongPoint().setLatitude(37.429379).setLongitude(
locations.add(new LatLongPoint().setLatitude(37.333646).setLongitude(



$locations = array(
    '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


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 loyalty card is moved to the "Expired passes" section if at least one of the following conditions is true:

  • The of the loyalty card has passed. The pass may move to "Expired passes" anytime up to 24 hours after
  • The state field of LoyaltyObject is marked as Expired, Inactive, or Completed.

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:{<issuerId>}.{<ObjectId>}

The pass can be viewed with the Google Pay app or a web browser.

Send feedback about...

Google Pay for Passes