Configure fallback barcodes

When to use a fallback barcode

Apple Wallet requires iOS 27 or later for the following barcode formats:

• Codabar
• Code 39
• EAN-13
• Interleaved 2 of 5

When you use these formats, add a fallback barcode in a format that earlier iOS versions can display. Google Wallet supports all four, so no fallback is required.

How barcode fallback works

A pass can have one primary barcode and multiple fallback formats. Configure the primary barcode in headers.barcode_type and the fallbacks in a top-level barcodes array. You can set both on a template, Adaptive Link, or pass. The barcodes array requires a primary barcode set with barcode_type.

Apple Wallet uses the first barcode that the device can display. The primary barcode comes first, followed by the fallbacks in the order you list them in the array, so list your preferred formats first.

Passes inherit the primary and fallback barcodes from their template. Adaptive Link and pass payloads can override the template settings.

Confirm that your scanners can read the primary barcode and each fallback.

Fallback barcode fields

Each fallback entry in the barcodes array has these fields:

• type: Required. The barcode format. Choose a format that matches the data and scanners used at redemption. See Barcode Types for the supported values.
• value: Optional value encoded in the barcode. If omitted, the primary barcode’s or template’s value is used. Use the same value for each format unless your scanning system requires different ones. It must be valid for the format. For example, EAN-13 requires 13 digits, while Codabar commonly requires start and stop characters.
• altText: Optional human-readable text displayed with the barcode.
• encoding: Optional character encoding. The default is ISO 8859-1.

Fallback barcode example

The following Patch template request sets Codabar as the primary barcode and QR as the fallback.

PATCH /templates/12345 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
  "headers": {
    "barcode_type": {
      "fieldType": "barcode",
      "formatType": "String",
      "value": "CODABAR"
    },
    "barcode_value": {
      "fieldType": "barcode",
      "formatType": "String",
      "value": "A123456789B"
    },
    "barcodeAltText": {
      "fieldType": "barcode",
      "formatType": "String",
      "value": "123456789"
    },
    "barcode_encoding": {
      "fieldType": "barcode",
      "formatType": "String",
      "value": "iso-8859-1"
    }
  },
  "barcodes": [
    {
      "type": "QR_CODE",
      "value": "A123456789B",
      "altText": "123456789",
      "encoding": "iso-8859-1"
    }
  ]
}