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 event ticket vertical:

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 fields for all of the event tickets for a specific event, such as when the venue address changes, you only need to update or patch the EventTicketClass or use the Google Pay Merchant Center. Google propagates this information to all EventTicketObjects associated to the updated EventTicketClass. This is the case for all fields defined at the EventTicketClass level.

To update a single pass, such as when the seat number for one ticket holder changes, you need to update or patch a single EventTicketObject. This is the case for all fields defined at the EventTicketObject 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 EventTicketClass list method. You can find all objects of a particular class if you call the EventTicketObject list method.

Make a button to save multiple passes

If a user buys multiple passes, and they're likely to save all of them to Google Pay, then it's useful to allow a user to save many objects with one click of a Save to Google Pay button or link. You can define multiple objects or classes when you sign the JSON Web Token (JWT).

You must create the JWT in either of the following formats:

  • With pre-inserted classes and objects only.
  • With only object and class resources that are fully defined within the JWT.

For an example of how to create a button for multiple passes, see Save multiple attendees button.

For more information on the UI representation of Passes, see Group event tickets.

Group event tickets

There are features which work differently if they're used on a group rather than individual objects, such as status notifications, or the organization of multiple saved Passes in the user interface.

The conditions by which EventTicketObject are considered to be a group depend on whether or not the class.eventID property is defined.

Group with class.eventId

The class.eventId property can group tickets, regardless of other properties. For example, if two EventTicketObject objects have class.eventId = "foo", even if they have different class.eventName and class.dateTime.start, both objects are considered to be in a group.

When class.eventID is used, objects only require the following properties to be consistent in order to be considered as a group.

  • Issuer ID (from Google Pay API for Passes Merchant Center)
  • class.eventId

Group without class.eventId

If class.eventId isn't set for EventTicketObject objects, they're only considered a group if all of the properties listed below are the same:

  • Issuer ID (from Google Pay API for Passes Merchant Center)
  • class.eventName
  • class.dateTime.start

Upcoming event notification

Google Pay sends a notification to the user three hours prior to the event. The event time is defined by class.dateTime.start.

To receive this notification, the user must have notifications enabled. To check this, they can navigate to Settings > Notifications and see if Updates about your passes is turned on.

The notification shows up in the notifications area, and in the lock screen, if the user has notifications enabled for the lock screen

The notification has the following unmodifiable format:

class.eventName
Expand for more options

If they tap the notification and unlock their device, their pass appears in the Google Pay app.

If the user has multiple passes, only the soonest useable pass is shown. If they've saved grouped passes as per Group event tickets, the notification only shows one of the passes in the group. However, when they tap it, the user can swipe left and right to see the other passes in that group.

The notification is pinned and won't auto-dismiss after a user opens it. Auto-dismiss occurs 60 minutes after class.dateTime.end. If no class.dateTime.end time is provided, class.dateTime.start is used instead..

Linked offers

Linked offers allow existing offers to appear within the event ticket view, making relevant content easier for the user to discover. The writable list field linkedOfferIds in a EventTicketObject indicates which offers are associated with the event ticket.

Creating the offer before linking

To link a linked offer, the offer classes and objects linked to the event ticket must already be created. To learn more about creating offers, see Offers. Unlike standalone offers, linked offers do not require a user to explicitly save the offer. The id field found in the OfferObject is used to point to the EventTicketObject.

Link offers to an event ticket

The existing offers can be linked to an event ticket using the REST API calls insert, or update, or patch, or modifyLinkedOfferObjects.

When offers are linked to an event ticket upon creation of the event ticket using the insert call or when offers are both linked and unlinked to an existing event ticket using the update call, the field linkedOfferIds can be written with the rest of the EventTicketObject using the established format:

{
  "id": "2945482443380251551.ExampleObject1",
  "classId": "2945482443380251551.ExampleClass1",
  ...
  "linkedOfferIds": [
    "2945482443380251551.OfferObject1",
    "2945482443380251551.OfferObject2"
  ]
}

When offers are linked and unlinked to an existing event ticket using the patch call, the field linkedOfferIds can be the only field in the request:

{
  "linkedOfferIds": [
    "2945482443380251551.OfferObject1",
    "2945482443380251551.OfferObject2"
  ]
}

However, in order to avoid mistakes whe dealing with arrays, specify which linked offers need to be added and which need to be removed, and be able to omit the linked offers that should remain untouched, we recommend to use the modifyLinkedOfferObjects method as in the following example:

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

Designing event ticket with linked offers

Linked offers will appear in an event ticket view between the card section and the details section, as shown below. Only a maximum of 5 linked offers are displayed in the carousel. If more offers are linked to the event ticket, the user can click on the "More" button at the end of the carousel to display them all.

Linked offers

When clicked the linked offer uses a simplified offer design, as shown below.

Linked offer clicked

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:

  • It's been at least 72 hours since class.dateTime.end expired. If class.dateTime.end isn't specified, class.dateTime.start is used instead. The pass moves to "Expired passes" anytime between 72-96 hours after class.dateTime.end or class.dateTime.start expires.
  • object.validTimeInterval.end.date expires. The pass moves to "Expired passes" anytime up to 24 hours after object.validTimeInterval.end.date expired.
  • The object.state field 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:

https://pay.google.com/gp/v/object/{<issuerId>}.{<ObjectId>}

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