# Apple Wallet Pass Field Limits, Style by Style

> How many fields an Apple Wallet pass shows: 3 header, 1 primary, 4 secondary, 4 auxiliary, but only 4 combined on QR store cards. Plus the row-width budget.

Canonical: https://cardr.co/blog/apple-wallet-pass-field-limits
Author: Kai, Founder of Cardr. Published 2026-09-23; last updated 2026-09-23.
Part of: [Apple Wallet business cards](https://cardr.co/apple-wallet-business-card)

## Short answer

**An Apple Wallet pass can show up to three header fields, one primary field, four secondary and four auxiliary fields. But coupons, store cards and generic passes with a square barcode (QR or Aztec) get four secondary and auxiliary fields combined, not eight. Event tickets keep four and four; boarding passes get two primary and five auxiliary.** The binding limit in practice is width: each row is one line of about 345 points that truncates rather than wraps, which we measure at roughly 42 characters shared between its columns.

## The limits, style by style.

Apple states them in one paragraph of its PassKit guide. Every number in this table is imported from the module our own pass builder is validated against, which quotes that paragraph beside the code.

Apple’s wording, from the [Wallet Developer Guide](https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html): “In general, a pass can have up to three header fields, a single primary field, up to four secondary fields, and up to four auxiliary fields. Boarding passes can have up to two primary fields and up to five auxiliary fields. Coupons, store cards, and generic passes with a square barcode can have a total of up to four secondary and auxiliary fields, combined.”

Front-of-pass field limits by pass style

| Style | Header | Primary | Secondary | Auxiliary | Secondary + auxiliary with a QR |
| --- | --- | --- | --- | --- | --- |
| Generic | 3 | 1 | 4 | 4 | **4 combined** |
| Store card | 3 | 1 | 4 | 4 | **4 combined** |
| Coupon | 3 | 1 | 4 | 4 | **4 combined** |
| Event ticket | 3 | 1 | 4 | 4 | Independent |
| Boarding pass | 3 | 2 | 4 | 5 | Independent |
| Poster generic (iOS 27) | 1 | Up to 4 | — | — | Uses 2 footer fields instead |

The first five rows are imported from `src/pass-generator/pass-spec.js`, which quotes Apple’s [PassKit guide](https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html) beside each number. The poster generic row is quoted from [Apple’s poster generic documentation](https://developer.apple.com/documentation/walletpasses/creating-a-poster-generic-pass) and is not in our spec, because nothing we ship uses it.

Back fields are not in that paragraph. Apple’s newer generic-pass documentation says the back “can have as many fields as you need, and the contents of the fields can be longer”. That is where long values belong: links, an address, a bio.

## The combined rule is the one that bites.

A store card, coupon or generic pass with a QR code does not have eight slots under the primary row. It has four, shared between secondary and auxiliary.

Most people read the first sentence of Apple’s paragraph, count eight fields and fill them. On any pass whose barcode is square, which in practice means every pass with a QR, the last sentence halves that. A square barcode is `PKBarcodeFormatQR` or `PKBarcodeFormatAztec`; PDF417 and Code 128 are rectangular and leave the full budget in place.

Event tickets and boarding passes are not named in that sentence, so they keep their secondary and auxiliary budgets separately. Two things follow. If you need more than four front fields with a QR, event tickets are the style that offers it (boarding passes do too, but need a transit type). And whatever you exceed, nothing tells you: Wallet adds the pass and simply leaves the extra fields off. Apple’s own note on this is worth taking literally: “Do not include more fields than are displayed on the front of your pass. Although additional fields may not be shown today, layouts may change in the future.”

This is why our builder’s validator treats `combined-overflow` as an error and throws in development, so a pass that breaks the rule fails on our machines rather than silently on a phone. The same budgets, with the rest of the format, are in the [Apple Wallet pass guide](https://cardr.co/apple-wallet-pass-guide#fields).

## Width is the real budget.

Each front row is laid across one line of about 345 points and truncated rather than wrapped. Measured at 15pt, that is roughly 42 characters, shared between however many columns the row has.

Apple’s version is vague on purpose: “The number of fields displayed on the pass also depends on the length of the text in each field. If there is too much text, some fields may not be displayed.” The numbers below are ours, measured, not Apple’s. Treat them as a design budget rather than a guarantee, because font, weight and the characters themselves all move them.

One 345pt row, split one to four ways, drawn to scale. Character counts are measured at 15pt; `ROW_CHARS = 42` in pass-spec.js is the number our builder and the viewer both work to.

Nine characters is not really a field. Put four values in a row and a single long one, an email address, say, truncates to an ellipsis, and at that width so does most of what sits beside it. Four columns of ellipses carry less than one column of text.

## Pack rows greedily, then stop.

Our builder does not fill slots because they exist. It adds values to a row in priority order while every value still fits the width its column drops to, and skips any that would not.

This is the function, as it ships in `build-pass-json.js`. The test is simple: a row of *n* columns can hold a value only if its length times *n* stays within 42. That puts the hard cut-offs at 42, 21, 14 and 10 characters, a little above the measured comfortable figures.

`**// build-pass-json.js** function packRow(candidates, limit) { const row = []; for (const f of candidates.filter(Boolean)) { if (row.length >= limit) break; const next = [...row, f]; if (next.some((x) => String(x.value).length * next.length > CHARS_PER_ROW)) continue; row.push(f); } return row; }`

`limit` is the style’s slot count from pass-spec.js; `CHARS_PER_ROW` is ROW_CHARS. A value that does not fit is skipped, not truncated, and the next one is tried.

Here is what it does with a real card. The table is the output of our pass builder for one demo holder, run when this page was built, in two styles. On the store card, which ships, the name is drawn into the strip image so the primary field stays empty, and the front carries one secondary and one auxiliary field: well inside the four combined. On the event ticket, which has four and four, the four short values pack four-up into the secondary row. The email is 29 characters, so it takes the auxiliary row alone, and the phone number is left for the back rather than squeezed in beside it.

One demo card, as our pass builder lays out its front

| Field group | Store card (ships) | Event ticket (4 + 4) |
| --- | --- | --- |
| Header | *none* | *none* |
| Primary | *none* name is in the strip image | Kai |
| Secondary | Founder | **ROLE** Founder **COMPANY** Novrex **WEB** novrex.co **LOCATION** London |
| Auxiliary | +44 20 7946 0123 | **EMAIL** kai.morgan.studio@example.com |

Generated by `buildPassJson()` from a demo card when this page was built. The holder, email and number are examples, not a real person. Everything omitted from the front is on the back of the pass.

## Poster styles change the numbers.

Apple’s newer poster layouts use a different set of fields. Nothing here ships them, so these numbers are Apple’s, quoted, and not checked against a device.

- **Poster generic (iOS and watchOS 27).** Apple: “A Poster Generic Pass can have a header field, up to four primary fields, two footer fields, back fields, and additional info field.” You add a `posterGeneric` dictionary alongside a legacy style, and older devices show the legacy one. Source: [Creating a Poster Generic Pass](https://developer.apple.com/documentation/walletpasses/creating-a-poster-generic-pass).
- **Poster event ticket.** Driven by semantic tags rather than field counts, with a legacy event ticket as the fallback. Apple states plainly that “poster event tickets aren’t compatible with tickets that require a QR code or barcode for entry”, which rules it out for anything scanned, business cards included. Source: [Creating a poster event pass using semantic tags](https://developer.apple.com/documentation/walletpasses/creating-an-event-pass-using-semantic-tags).

Because both fall back to the legacy style on older devices, the legacy limits above still decide what a large share of phones show.

## Check a pass before you ship it.

Our free .pkpass viewer counts the fields in any pass against its style, applies the combined rule when the barcode is square, and flags values likely to truncate. It runs in the browser and does not upload the file.

Open a pass in the [.pkpass viewer](https://cardr.co/tools/pkpass-viewer) and it reports each field group against the budget in the table above, from the same module this page imports. For image sizes the same way, see [Apple Wallet pass image sizes](https://cardr.co/blog/apple-wallet-pass-image-sizes); for everything else about the format, the [Apple Wallet pass guide](https://cardr.co/apple-wallet-pass-guide).

If what you actually want is a business card in Wallet rather than a pass to build, [Cardr issues one](https://cardr.co/apple-wallet-business-card), already packed to these limits, on the free plan.

## Questions, answered

### How many fields can an Apple Wallet pass have?

On the front, up to three header fields, one primary field, four secondary and four auxiliary. Boarding passes get two primary and five auxiliary. Coupons, store cards and generic passes with a square barcode get four secondary and auxiliary fields combined. The back has no documented limit.

### Why are my auxiliary fields not showing on my store card?

Almost always the combined rule. A store card with a QR or Aztec code shows at most four secondary and auxiliary fields between them. If you have three secondary fields, only one auxiliary field has room.

### Does Wallet wrap long text in a field?

No. Front-of-pass fields sit on one line and truncate. Apple says only that if there is too much text some fields may not be displayed; in our measurements a full row holds about 42 characters at 15pt, shared between its columns.

### What counts as a square barcode?

PKBarcodeFormatQR and PKBarcodeFormatAztec. PDF417 and Code 128 are rectangular, and the combined four-field rule does not apply to passes that use them.

### Do event tickets have the combined field limit?

No. Apple names only coupons, store cards and generic passes in the combined rule, so an event ticket keeps four secondary and four auxiliary fields even with a QR code.

### Where should long values like an email or address go?

On the back of the pass, where fields can be longer and there is no documented cap, or on a front row by themselves. Putting a long value in a three- or four-column row truncates it.

---

Written by Kai for Cardr (https://cardr.co), a UK digital business card issued as a signed Apple Wallet pass. The card is free; Pro is £12/month, or £9/month billed annually (£108 a year). Prices and plans: https://cardr.co/pricing.md