Boarding pass overrides

You can customize fields in the Card Template area of Google boarding passes, providing flexibility when designing your boarding passes.

Boarding pass templates rely on Google’s default pass designs. You can override the placement and order of fields on your templates through the wallet template editor or the wallet API.

If you are using the Update Template API to override the layout of a pass, it may help you to first view the template in the template editor to better understand its current layout.

Google Pass Layout

Google passes are organized into sections, each of which has a default layout. You can pass overrides when creating your boarding pass template to customize the labels and layout of fields in the sections listed below.

When you override the label or position of a field in one of these sections, you must override all the fields in that section.

 Note

You cannot override the Card Title section.

You can override the following sections:

  1. cardTemplate: Supports 2 rows, 3 columns of information. You can override the area in this part of the template.
  2. barcodeSection: The barcode area of the template.
  3. detailsTemplate: A list of pass details below the barcode.
  4. listTemplate: The pass details that users see in their wallet before they open their pass.

The Card Title

You can’t override fields in the card title section of a boarding pass template. This includes the fields shown below. In the case of the departureAirport, and arrivalAirport, we show both the label and value on the pass.

Fields on the card template are all populated from the flight object — either in the /flights API or as a part of an object within an array of payload.flights in an adaptive link request. The table below lists the items on the template and the flight object values that populate the template field when you create a pass.

Required items in the table below represent the required properties in the adaptive link payload, and are therefore required to be on a pass. While other fields may not be required, and you can hide them if empty, you may want to leave them blank and populate them as the departureTime approaches so your passengers know where to look on the pass to find new information.

Moving a template on a field moves both the label and value keys, if both keys exist, for a flight or passenger.

 Note

While the API allows for label values at the template field and flight object level, Google does not typically allow you to override field labels for boarding passes. In most cases, label overrides at the flight level apply to Apple Wallet passes only.

The table below relates template field names to the keys that populate the template in the adaptive link payload.flights[] array of objects.

     Template fieldAdaptive Link key
payload.flights[]
Default labelRequired
1image
2airlineNamefields.airlineName.value
3flightNumber1fields.flightNumber.value
4departureAirportfields.departureAirport.label2
5fields.departureAirport.value
6arrivalAirportfields.arrivalAirport.label2
7fields.arrivalAirport.value

1 This field also appears in the detailsTemplate. You can override this field to change its placement elsewhere on the pass, but you cannot remove or change its placement on the card title.
2Typically set by the corresponding value property. You can override the Airport name using the label field, but you don’t have to set this value manually when creating flights.

The Card Template

The Card Template consists of 2 rows. The first row supports three columns. The second row supports 2 columns. All row/col combinations support subcol, allowing for 2 template fields per rectangle in the image below.

Required items in the table below represent the required properties in the adaptive link payload, and are therefore required to be on a pass. While other fields may not be required, and you can hide them if empty, you may want to leave them blank and populate them as the departureTime approaches so your passengers know where to look on the pass to find new information.

Moving a template on a field moves both the label and value keys, if both keys exist, for a flight or passenger.

 Note

While the API allows for label values at the template field and flight object level, Google does not typically allow you to override field labels for boarding passes. In most cases, label overrides at the flight level apply to Apple Wallet passes only.

The table below relates template field names to the keys that populate the template in the adaptive link payload.flights[] array of objects.

     Template fieldAdaptive Link key
payload.flights[]
Default labelRequired
1departureTerminalfields.departureTerminal.labelTERMINAL
2fields.departureTerminal.value
3departureGatefields.departureGate.labelGATE
4fields.departureGate.value
5seatClassPolicy1fields.seatClass.labelCABIN
6seatClasspassengers[].fields.seatClass
7boardingTime2fields.boardingTime.label
8fields.boardingTime.value
9passengerNamepassengers[].fields.passengerName.labelPASSENGER
10passengers[].fields.passengerName.value
11boardingGrouppassengers[].fields.boardingGroup.labelGROUP
12passengers[].fields.boardingGroup.value
13seatNumberpassengers[].fields.seatNumber.labelSEAT
14passengers[].fields.seatNumber

1The label changes based on the seatClassPolicy set on the flight.
2This field also appears on the detailsTemplate.

The Barcode Template

The barcode template consists of four rows. You can set default values for a few items on the template, but the barcode value itself is populated from the headers in your template or adaptive link with a confirmationCode value set for each passenger.

Required items in the table below represent the required properties in the adaptive link payload, and are therefore required to be on a pass. While other fields may not be required, and you can hide them if empty, you may want to leave them blank and populate them as the departureTime approaches so your passengers know where to look on the pass to find new information.

Moving a template on a field moves both the label and value keys, if both keys exist, for a flight or passenger.

 Note

While the API allows for label values at the template field and flight object level, Google does not typically allow you to override field labels for boarding passes. In most cases, label overrides at the flight level apply to Apple Wallet passes only.

The table below relates template field names to the keys that populate the template in the adaptive link payload.flights[] array of objects.

     Template fieldAdaptive Link key
payload.flights[]
Default labelRequired
1headers.securityProgramLogo
2headers.boardingPrivilegeImage
3headers.barcode_valuepassengers[].fields.confirmationCode 
4headers.barcodeAltText
5headers.airlineAllianceLogofields.airlineAllianceLogo

The Details Template

The detailsTemplate supports a number of single-column rows, each supporting subcol — two items separated by a /. Generally, website and image rows on the details template, are set at the template level, though you can set them within an adaptive link payload by providing a field object (with label and/or value keys) outside of the flights object.

Required items in the table below represent the required properties in the flight or passenger objects when creating adaptive links, and are therefore required to be on a pass. While other fields may not be required, and you can hide them if empty, you may want to populate these fields as the departureTime approaches.

Moving a template on a field moves both the label and value keys, if both keys exist, for a flight or passenger.

 Note

While the API allows for label values at the template field and flight object level, Google does not typically allow you to override field labels for boarding passes. In most cases, label overrides at the flight level apply to Apple Wallet passes only.

The table below relates template field names to the keys that populate the template in the adaptive link payload.flights[] array of objects.

     Template fieldAdaptive Link key
payload.flights[]
Default labelRequired
1boardingPositionPosition
2passengers[].fields.boardingPosition.value
3sequenceNumberSequence
4passengers[].fields.sequenceNumber.value
5boardingDoorBoarding Door
6passengers[].fields.boardingDoor.value
7flightNumberFlight Number
8fields.flightNumber.value
9confirmationCodeConfirmation Code
10passengers[].fields.confirmationCode.value
11eticketNumberTicket Number
12passengers[].fields.eticketNumber.value
13frequentFlyerNumber
frequentFlyerProgramName
Frequent Flyer Number1
14passengers[].fields.frequentFlyerProgramName.value
passengers[].fields.frequentFlyerNumber.value
15boardingTimefields.boardingTime.labelBoarding Time
16fields.boardingTime.value
17gateClosingTimefields.gateClosingTime.labelGate Closes
18fields.gateClosingTime.value
19departureTimefields.departureTime.labelScheduled
20fields.departureTime.value
21actualDepartureTimefields.actualDepartureTime.labelEstimated Departure
22fields.actualDepartureTime.value
23arrivalTimefields.arrivalTime.labelScheduled
24fields.arrivalTime.value
25actualArrivalTimefields.actualArrivalTime.labelEstimated Arrival
26fields.actualArrivalTime.value
27arrivalTerminalfields.arrivalTerminal.labelArrival Terminal
28fields.arrivalTerminal.value
29arrivalGatefields.arrivalGate.labelGate
30fields.arrivalGate.value
31boardingPrivilegeImage
32Random Information1
33Website1

1These fields are part of default templates created through the Airship user interface. You can set their values at the template level or set them at the adaptive link level, if you want the value(s) should change.

Template Overrides

You can override the order of items in a section of your template, or the information in a template section, by specifying an overrides object. This object contains the section(s) that you want a field to appear in and the order or placement of a field in that section using row, col, and subcol properties.

Two fields can occupy the same row and col. Use the subcol to determine the order of fields in the same row and column positions.

In the example below, we’ll move the boardingTime and departureGate to the second row (index 1) and first column on the card template. Because these two fields will occupy the same space on the template, we’ll also set the subcol to ensure that the boarding time appears first.

 Note

If you override a field in a template section, you must set overrides for all fields in that section. Fields without an override in a section that uses overrides will not appear in a section or on your passes.

Set overrides for boarding pass fields
{
    "boardingTime": {
        "fieldType": "flightModule",
        "value": "",
        "formatType": "String",
        "label": "",
        "hideEmpty": false,
        "required": false,
        "overrides": {
            "cardTemplate": {
                "row": 1,
                "col": 0,
                "subCol": 0,
                "dateStyle": "timeOnly"
            }
        }
    },
    "departureGate": {
        "fieldType": "flightModule",
        "value": "",
        "formatType": "String",
        "label": "",
        "hideEmpty": false,
        "required": false,
        "overrides": {
            "cardTemplate": {
                "row": 1,
                "col": 0,
                "subCol": 1
            }
        }
    }
}

Boarding pass with default fieldsBoarding pass with overrides

Override a Template

The card template consists of up to two rows, with up to three items per row (left, center, and right). You can add or move fields around the cardTemplate to better organize your passes.

 Note

We recommend testing overrides with a duplicate template before modifying a template that is associated with live passes. The steps here include duplication, creating an Adaptive LinkA vendor-agnostic, shortened mobile wallet pass link that supports templates for both Google Wallet and Apple Wallet. When a user taps the link, Airship determines the user’s platform and generates the right pass for that platform. , and viewing the passes on local devices to verify that your overrides perform the way you expect.

You must have at least one Apple Wallet and one Google Wallet template to create an adaptive link.

  1. Duplicate an Apple Wallet or Google Wallet template you want to override, and use its templateId in the following steps.

  2. Use the /templates API to get your template payload. This call, as opposed to the /v1/template endpoints, returns a template payload in exactly the same format as you would use in a POST or PUT operation.

    GET /templates/160571 HTTP/1.1
    Authorization: Basic <authorization string>
    Content-type: application/json

  3. Update your template with overrides using a PATCH against the /templates/{templateId} endpoint. In the payload, you only need to provide the fields in your template that you want to override.

     Note

    If your template contains fields that aren’t a part of the default template design, like fareType or departureGate, they must contain label and value keys. You can set empty strings in your template and replace these values when you generate passes, but failing to set label or value keys will prevent those fields from rendering properly on your pass.

    PATCH /templates/<templateId> HTTP/1.1
    Authorization: Basic <authorization string>
    Content-type: application/json
    
    {
    	"fields": {
    		"passengerInfo": {
    			"fieldType": "infoModuleData",
    			"value": "First/Last",
    			"formatType": "String",
    			"label": "PASSENGER",
    			"order": 5,
    			"overrides": {
    				"cardTemplate": {
    					"row": 0,
    					"col": 0
    				}
    			}
    		},
    		"boardingPosition": {
    			"fieldType": "flightModule",
    			"value": "___",
    			"formatType": "String",
    			"label": "POSITION",
    			"hideEmpty": false,
    			"required": false,
    			"overrides": {
    				"cardTemplate": {
    					"row": 0,
    					"col": 1
    				}
    			}
    		},
    		"departureGate": {
    			"fieldType": "flightModule",
    			"value": "__",
    			"formatType": "String",
    			"label": "",
    			"hideEmpty": false,
    			"required": false,
    			"overrides": {
    				"cardTemplate": {
    					"row": 0,
    					"col": 2
    				}
    			}
    		},
    		"fareType": {
    			"fieldType": "infoModuleData",
    			"value": "__",
    			"formatType": "String",
    			"label": "FARE",
    			"hideEmpty": false,
    			"required": false,
    			"order": 2,
    			"overrides": {
    				"cardTemplate": {
    					"row": 1,
    					"col": 0
    				}
    			}
    		},
    		"boardsOrEmptyInfo": {
    			"fieldType": "infoModuleData",
    			"value": "",
    			"formatType": "String",
    			"label": "BOARDS",
    			"hideEmpty": false,
    			"required": false,
    			"order": 6,
    			"overrides": {
    				"cardTemplate": {
    					"row": 1,
    					"col": 1
    				}
    			}
    		},
    		"boardsOrSecurityInfo": {
    			"fieldType": "infoModuleData",
    			"value": "__",
    			"formatType": "String",
    			"label": "__",
    			"hideEmpty": false,
    			"required": false,
    			"order": 7,
    			"overrides": {
    				"cardTemplate": {
    					"row": 1,
    					"col": 2
    				}
    			}
    		}
    	}
    }

  4. Repeat steps 2 and 3 for the other platform so that you have will have updated templates for both Apple Wallet and Google Wallet.

  5. Create an adaptive link for the updated template IDs, using the API or dashboard. Your adaptive link must include passenger information:

    • For passengers, both passengerName and confirmationCode are required fields.
    • For flights, departureTime, departureAirport, arrivalAirport, flightNumber, and airlineCode are required fields.
  6. Paste the adaptive link in local Android and iOS devices, save the passes, and confirm they appear as you expected.

  7. If the passes appear as expected, repeat steps 1-2 for your original templates.

  8. (Optional) Confirm the appearance of the passes based on your original templates, and delete the duplicate templates you used for testing.

Reverting Boarding Pass Template Overrides

If you want to revert a template section to the default layout, update your template with an empty overrides object.

Use Default Layout
{
    "departureGate": {
        "fieldType": "flightModule",
        "value": "",
        "formatType": "String",
        "label": "",
        "hideEmpty": false,
        "required": false,
        "overrides": {}
    }
}

Override properties

The overrides a group of objects, each representing an individual override for the field. All Integer properties are 0-indexed.

overrides: an object with child properties for each section where a field will appears on a pass. Supported child objects: cardTemplate, barcodeSection, detailsTemplate, listTemplate. Set an empty object to reset a field to the default layout.

row: Integer; the row the field should appear in. The number of available rows depends on the template type.

col: Integer; the column the field should appear in. There are 3 columns in the card template, 0 is the left column, 1 is the center, and 2 is the right column.

subcol: Integer, 0 or 1; when multiple fields use the same row and col, this determines whether a field appears on the left or the right in the column.

dateStyle: String; for fields that take ISO date-times, use dateStyle to override the default format for dates and times. Different fields have different default date styles. Accepted values:

  • date-time: Show both date and time
  • dateOnly: Display only the date
  • timeOnly: Display only the time
  • dateTimeYear: Display the date, time, and year
  • dateYear: Display the date and year

Example field override
{
    "boardingTime": {
        "fieldType": "flightModule",
        "value": "",
        "formatType": "String",
        "label": "",
        "hideEmpty": false,
        "required": false,
        "overrides": {
            "cardTemplate": {
                "col": 0,
                "row": 1,
                "subcol": 0,
                "dateStyle": "timeOnly"
            }
        }
    }
}

Date and Time Styles

Several fields in the flight object take date-time string values. By default board pass templates shape date-time values to fit their placement on the pass. For example, boardingTime only shows the time when the user boards a plane, rather than the full date and time. However, you can override the default date-time format for any field using the dateStyle key in an override object setting the following styles:

  • date-time: Show both date and time
  • dateOnly: Display only the date
  • timeOnly: Display only the time
  • dateTimeYear: Display the date, time, and year
  • dateYear: Display the date and year
 Important

If you override the dateStyle for a field, you must also set overrides for all of the fields within a template section.

You can use dateStyle with the following boarding pass fields.

FieldDefault style
boardingTimetimeOnly
arrivalTimedate-time
actualArrivalTimetimeOnly
departureTimedate-time
actualDepartureTimetimeOnly