Everything written on a pass is a field: a label and a value. Fields live in one of four regions, and the region decides where and how prominently it appears.
Getting this right is the difference between a pass someone can read at a glance and one they have to squint at.
The four regions
| Region | Slots | What it's for |
|---|---|---|
| Header | 2 | Small text at the very top, visible even when the pass is stacked behind others in the wallet. |
| Central | 2 | The headline. Biggest text on the pass. |
| Details | 6 | The supporting facts, in two rows of three. |
| Back | 6 | Everything else - terms, contact details, instructions. |
Each slot holds one field with a label, an optional default value, and an id generated from the label.
What goes where
Header is prime real estate because it's the part visible when passes are stacked. Put the one thing that identifies this pass at a glance - a member number, a seat, a balance.
Central is the headline. One or two words. A tier name, an event name, a status. Don't put a sentence here; it will be truncated.
Details is where most information belongs - dates, names, references, anything with a short label and a short value.
Back is for the things people need occasionally: terms and conditions, a phone number, redemption instructions, opening hours. Nobody reads the back casually, but it's where they'll look when they need to.
Fill the front sparingly. A pass with four well-chosen fields reads far better than one with fourteen. Anything you're unsure about belongs on the back.
Default values, and per-pass values
Each field can carry a default value on the template. When you issue a pass you can override it.
The rule is straightforward: a pass shows its own value if it has one, otherwise the template's default, otherwise nothing.
That makes defaults useful for anything constant across every pass - "Valid at all locations", a support phone number - while genuinely per-customer fields are left blank on the template and filled in per pass.
Leaving a value blank when issuing a pass is not the same as setting it to empty. A blank falls back to the template default; that's deliberate, and it's why clearing a field on one pass shows the default rather than nothing.
Field ids are permanent
Beneath each label is an id, derived from the label the first time you save. That id is the key each pass's value is stored against.
- Renaming a label is safe. The id doesn't move and existing passes are unaffected.
- Deleting a field and creating a replacement is not the same thing. The new field gets a new id, so values already stored against the old one won't appear in it.
If you need to reword a field, edit its label. Don't delete it and add a new one - that orphans the values on every pass already issued.
Apple and Google show the same fields differently
This is the single most useful thing to know about pass design, and it catches everybody once.
Apple Wallet honours the regions closely:
- Header fields sit at the top.
- Central fields become the large primary text.
- The first three details become one row, the next three another.
- Back fields are on the reverse, behind the info button.
Google Wallet works differently. It uses one general-purpose card layout, and:
- The first central field becomes the card's main heading.
- The first header field becomes the subheading.
- Details and back fields are combined into a single list. Google doesn't distinguish front from back the way Apple does.
The practical consequences:
- Order matters more on Google. Put the important things in the earlier detail slots.
- The back isn't hidden on Google. Don't put anything on the back you'd be uncomfortable showing inline - it will be visible in the list.
- The first central field is doing the most work of any field on the pass. Choose it deliberately.
Use the Apple/Google toggle in the preview constantly while you design. It mirrors this behaviour exactly, so what you see is what gets issued.
A worked example
For a membership card:
- Header 1: "Member no." →
10248 - Central 1: "Tier" →
Gold - Details: "Name", "Member since", "Renews"
- Back: "Benefits", "Terms", "Contact us"
On Apple that reads as a card with a member number top-right, a large Gold, three facts underneath and the small print on the reverse. On Google it reads as a Gold card headed by the member number, with name, dates, benefits, terms and contact all listed together underneath.
Both are correct. Both are readable. That's the goal.
Editing fields as JSON
The builder has a Show advanced option that exposes the field structure directly. It's there for bulk edits and for copying a layout between templates. Most people never need it, and the visual editor is safer.
Where to go next
- Colours and images - the other half of the design.
- Barcodes.
- Issuing a pass - where those default values get overridden.