Use cases

Select one of the following pass verticals to learn more about how it can be used.

Boarding passes Event tickets Gift cards Loyalty
Offers Transit passes COVID cards

---

The Google Pay API for Passes allows you to engage with users through event tickets. The concepts discussed in this guide should help you better understand the capabilities of saved event tickets.

To implement event tickets, use the JWT POST request method or "skinny" JWT links, which are methods that pre-insert the classes and objects.

The following use cases are available only to the event ticket vertical:

• Update passes.
• Make a button to save multiple passes.
• Group event tickets.
• Receive upcoming event notification.
• Linked offers.
• Handle expired passes.
• Link to a saved pass.
• Link out from a saved pass.

Note: All Pass verticals share core functionalities. For more information, see Save passes to Google Pay, Redeem passes from Google Pay, and Engage users through Google Pay.

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.

Note: To understand more about the difference between update and patch, see Patch (partial update).

Any update logic should begin with a GET request to retrieve the class or object. This ensures that the latest version of the class or object is used. Fields that you omit are cleared.

In general, it's much safer to use patch when you only supply data for the fields that you want to change. Fields that you omit aren't cleared. However, you should take extra care when you modify arrays. Patch requests that contain arrays also replace the existing array with the one you provide. You cannot modify, add, or delete items in an array in a piecemeal fashion.

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.

Note: The format of the JWT must be consistent, so that only one format or the other is used.

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

If class.eventId is set, it takes precedence in order to determine what objects are considered to be in a group.

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

Note: class.dateTime.start is an optional property. If it isn't set, then only class.eventName and the Issuer ID are used to determine groups.

Receive upcoming event notifications

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

Important: Linked offers are temporarily unavailable for most users while we make platform improvements. We'll update this feature in an upcoming release.

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"
  ]
}

Note: If you update an existing EventTicketObject without the writable field linkedOfferIds, all offers are unlinked.

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"
  ]
}

Note: To unlink all linked offers with a patch call you must explicitly set the linkedOfferIds field to null or [].

However, in order to avoid mistakes when 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.

RECOMMENDED OFFERS offerObject.heroImage or offerClass.heroImage or mainObject.hexBackgroundColor or mainClass.hexBackgroundColor offerClass.localizedTitle or offerClass.title EXPIRES: offerObject.validTimeInterval.end

Note: If the hero image is missing in the linked OfferClass, the linked offer uses the background color of the EventTicketClass in this view.

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

offerObject.heroImage or offerClass.heroImage offerObject.barcode.type and offerObject.barcode.value offerObject.barcode.alternateText offerClass.localizedTitle or offerClass.title offerClass.details EXPIRES: offerObject.validTimeInterval.end offerClass.finePrint

Note: The simplified offer design always uses a white background.

Note: This image includes all fields necessary to complete the simplified offer design. However, not all of these fields are required to create a valid OfferClass or OfferObject. Refer to the OfferClass insert and the OfferObject insert methods for a list of required fields.

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.

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.

Note: If the user doesn't have the pass saved, they receive an "Item not found" error. If the user has the Google Pay app installed, the link works offline.

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.

Note: This feature is only available if you've completed two or more integrations with Google Pay for Passes API. These must be app, web, or email integrations.

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
              }
            }
    }
  }
  …
  …
  …
}