Passes Classes and Objects overview

Almost all of the passes you can issue for an end-user to save in their Google Wallet are defined by two components: a Passes Class and a Passes Object. Anytime you issue a pass to a user, you will need an instance of both a Passes Class and a Passes Object, which tells the Google Wallet API what type of pass to construct, as well as details to display on the pass, such as the value of a gift card or a ticketholder's name.

The Google Wallet API provides a predefined set of Passes Classes and Passes Objects that you create instances of, then use to create a pass that is issued to a user, such as GiftCardClass and GiftCardObject, GenericClass and GenericObject, and others.

Each Passes Class and Passes Object instance is defined as a JSON object, which has a set of required and optional properties that correspond to the specific use case intended for that pass type.

Passes Classes

Think of a Passes Class as a shared template that is used to create one or more passes you will issue to your users. A Passes Class defines a common set of properties that will be included in all passes that reference it.

For example, the following instance of the EventTicketClass defines the fields that are common to all issued tickets for an upcoming event(venue, event name, issuer, date/time).

{
  "id": "ISSUER_ID.EVENT_CLASS_ID",
  "issuerName": "[TEST ONLY] Heraldic Event",
  "localizedIssuerName": {
    "defaultValue": {
      "language": "en-US",
      "value": "[TEST ONLY] Heraldic Event"
    }
  },
  "eventName": {
    "defaultValue": {
      "language": "en-US",
      "value": "Google Live"
    }
  },
  "venue": {
    "name": {
      "defaultValue": {
        "language": "en-US",
        "value": "Shoreline Amphitheater"
      }
    },
    "address": {
      "defaultValue": {
        "language": "en-US",
        "value": "ADDRESS_OF_THE_VENUE"
      }
    }
  },
  "dateTime": {
    "start": "2023-04-12T11:30"
  },
  "reviewStatus": "UNDER_REVIEW"
}

Each instance of a Passes Class requires an id property, which you specify. This Class ID acts as a unique identifier that you will reference whenever you use it to create a new Passes Object instance.

Passes Objects

While an instance of a Passes Class specifies a set of shared properties to be used in one or more passes, a Passes Object specifies the unique details of a specific pass that is issued to a specific user.

For example, when an Event Ticket Pass is created with the Google Wallet API, an EventTicketObject instance includes properties for the seat assigned to that ticket since those values will be unique to each ticket issued.

{
  "id": "ISSUER_ID.OBJECT_ID",
  "classId": "ISSUER_ID.EVENT_CLASS_ID",
  "state": "ACTIVE",
  "seatInfo": {
    "seat": {
      "defaultValue": {
        "language": "en-us",
        "value": "9"
      }
    },
    "row": {
      "defaultValue": {
        "language": "en-us",
        "value": "L"
      }
    },
    "section": {
      "defaultValue": {
        "language": "en-us",
        "value": "45"
      }
    },
    "gate": {
      "defaultValue": {
        "language": "en-us",
        "value": "7C"
      }
    }
  },
  "barcode": {
    "type": "BARCODE_TYPE_UNSPECIFIED",
    "value": "BARCODE_VALUE",
    "alternateText": ""
  }
}

Each instance of a Passes Object requires an id property, which you specify. This Object ID acts as a unique identifier that you will reference when you issue the pass to a user.

How Passes Classes work with Passes Objects

Passes Objects must extend an instance of a Passes Class either by referencing its Class ID or including the full Passes Class definition. This relationship between a Passes Class and Passes Object instance means you can set and update properties that are common to all issued passes via the Passes Class instance, and properties unique to an individual pass in the Passes Object instance.

For example, the following diagram of a simple Event Ticket pass shows how the fields that are defined in the shared EventTicketClass, and the fields for a specific ticket defined in the EventTicketObject combine to construct the final issued pass. Note how the ID of the Passes Class is referenced in classId property of the Passes Object.

Changes made to a Passes Class instance instance will propagate immediately across all Passes Object instances that reference it. Users will see any changes you make to a Passes Class instance reflected on the pass in their Google Wallet app the next time they sync.

Adding a pass to a user's Google Wallet

To add a pass to a user's Google Wallet, you create a JSON Web Token (JWT) that contains claims you (the issuer) are making about the Passes Object instance that will be saved in the user's Google Wallet - most importantly, the Object ID of the Passes Object instance you are issuing to the user. The JWT is then delivered to the user via the a Add to Google Wallet button or an Add to Google Wallet link.

After a user clicks the button or link to add an issued pass into their Google Wallet, a link the Passes Object instance encoded in the JWT is linked to that user's Google account. This means that when the user clicks the button again, a link already exists to that Passes Object, so duplicate copies won't be added to the user's wallet.

If a user removes a pass from the Google Wallet app, the corresponding Passes Object instance is automatically de-linked from the user, but it is not deleted. This means that a user can click the Add to Google Wallet button or link again, to save the pass without the need for a new Passes Object instance or JWT to be created.