Boarding pass overrides

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.

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.

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

¹ 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.
²Typically 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.

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

¹The label changes based on the seatClassPolicy set on the flight.
²This 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.

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

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.

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

¹These 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.

{
    "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 fields

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

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.

{
    "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

{
    "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

You can use dateStyle with the following boarding pass fields.