A working reference for the .pkpass format: every image allotment in points and in the pixels you export, the exact image set each pass style renders, the front-of-pass field budgets, and the five things Wallet does silently that the documentation never mentions.
An Apple Wallet pass is a signed ZIP archive with a .pkpass extension. Apple specifies every image in points and never gives you the pixel file you have to export, and states the field limits in a paragraph rather than a table. Both are below, generated from the same module our own pass builder reads, and last checked against Apple's documentation on 4 August 2026.
generic, storeCard, coupon, eventTicket, boardingPass. The style decides which images render and how many fields fit.Apple gives you points. Your export dialog wants pixels. This is the multiplication, done.
| Image | Allotted space | @1x | @2x | @3x |
|---|---|---|---|---|
icon.png |
29 × 29 pt | 29 × 29 | 58 × 58 | 87 × 87 |
logo.png |
160 × 50 pt | 160 × 50 | 320 × 100 | 480 × 150 |
thumbnail.png |
90 × 90 pt | 90 × 90 | 180 × 180 | 270 × 270 |
footer.png |
286 × 15 pt | 286 × 15 | 572 × 30 | 858 × 45 |
background.png |
180 × 220 pt | 180 × 220 | 360 × 440 | 540 × 660 |
strip.png Event ticket |
375 × 98 pt | 375 × 98 | 750 × 196 | 1125 × 294 |
strip.png Store card |
375 × 144 pt | 375 × 144 | 750 × 288 | 1125 × 432 |
strip.png Coupon |
375 × 144 pt | 375 × 144 | 750 × 288 | 1125 × 432 |
Allotments quoted from Apple's PassKit Package Format Reference. Pixel dimensions are the allotment multiplied by the scale factor; Apple publishes the points only. Ship @2x and @3x. A pass that carries only @1x is soft on every iPhone made in the last decade.
This is Apple’s Table 4-1, with the event ticket exception folded into the table instead of left in a sentence underneath it.
| Pass style | Images displayed | Strip allotment |
|---|---|---|
| Generic | logo, icon, thumbnail |
— |
| Store card | logo, icon, strip |
375 × 144 pt |
| Coupon | logo, icon, strip |
375 × 144 pt |
| Event ticket | strip layout: logo, icon, stripbackground layout: logo, icon, background, thumbnail |
375 × 98 pt |
| Boarding pass | logo, icon, footer |
— |
Every style also carries icon.png, which is not optional: it is what appears on the lock screen and in notifications. An image outside a style's set is not an error. Wallet ignores it, but it is still hashed into manifest.json and covered by your signature, so it is dead weight you are paying to sign.
The event ticket rule, verbatim: If you specify a strip image, do not specify a background image or a thumbnail.
Those are two mutually exclusive layouts sharing one style key, and nothing in the file format tells them apart. Wallet infers the layout from which images you shipped. Ship both and you have not chosen; you have left it to be decided for you.
Four columns, five styles, and a footnote that quietly halves your budget the moment you add a QR code.
| Pass style | Header | Primary | Secondary | Auxiliary | With a square barcode |
|---|---|---|---|---|---|
| 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 | not capped |
| Boarding pass | 3 | 2 | 4 | 5 | not capped |
The last column is the rule that catches people. Apple: Coupons, store cards, and generic passes with a square barcode can have a total of up to four secondary and auxiliary fields, combined.
Event tickets and boarding passes are absent from that sentence, so they keep both budgets in full. A square barcode means PKBarcodeFormatQR or PKBarcodeFormatAztec.
None of these are in the documentation. All five cost us time, and four of them fail without an error.
The field limits above tell you how many values fit. They do not tell you how many characters fit, and that is the number that decides whether your pass looks finished. Wallet lays each row across roughly 345 points and truncates rather than wrapping. Measured at 15pt, a one-column row takes about 42 characters, a two-column row about 20, three columns about 13 and four columns about 9.
Nine characters is not a field. Put a long email address in a four-column row and it does not shrink to fit; it truncates, and so does everything sitting beside it. Four columns of ellipses is less information than one column of text. Pack rows greedily against a width budget and stop, rather than filling every slot because the slot exists.
If you put thumbnail.png in a store card bundle, nothing happens. No warning, no validation error, no log line. The file is hashed into manifest.json, covered by your signature, downloaded to the device, and ignored.
The failure mode this produces is worse than a crash, because it runs in both directions at once and neither is visible. We shipped store cards carrying a thumbnail Wallet has no slot for, while the generic passes that do have a slot shipped none, for weeks. Nothing downstream ever reported it. If you take one thing from this page: derive your image set from the style programmatically, and make a mismatch fail your build.
Apple states the field capacity in a single paragraph, and the sentence that matters is the last one: Coupons, store cards, and generic passes with a square barcode can have a total of up to four secondary and auxiliary fields, combined.
Read quickly, that looks like a note about barcodes. It is not. It is a hard halving of your front-of-pass capacity from eight fields to four, and it applies to almost every pass that is not a ticket, because almost every pass that is not a ticket uses a QR code. Event tickets and boarding passes are absent from that sentence and keep four secondary plus four auxiliary in full.
Pass images are static PNG. APNG is not supported. Animated GIF is not supported. Wallet renders a still frame or nothing, with no error either way.
The confusion is real and it has a cause: Google Wallet does support GIF, so a good deal of advice written for one wallet gets applied to the other. There is no supported way to make an Apple Wallet pass front move, and there has not been one at any point in the format's history.
iOS 18 introduced a full-bleed poster layout for event tickets, and it is genuinely the best-looking thing the format can do. It is requested with preferredStyleSchemes: ["posterEventTicket"], and if you try it you will find it does nothing.
It renders only for NFC-enabled passes signed with an NFC certificate. Apple grants that entitlement to transit, ticketing and access-control partners after a business review; it is not something you enable in the developer portal. It also requires one of semantics.venueName, venueRegionName or venueRoom to be set. Without the entitlement the pass silently falls back to the standard layout, which is at least a graceful failure, and is still a failure you will spend an afternoon on.
Cardr issues a signed .pkpass for every card, so these rules are not trivia to us. Every number on this page is generated at render time from pass-spec.js, the single module our pass builder derives its image sets and field budgets from. If a limit here is wrong, our own passes break the same rule, which is the only accuracy guarantee that is worth anything.
Use it, quote it, screenshot the tables. If it saved you an afternoon, a link back is welcome and is not required.
Primary source: PassKit Package Format Reference — Creating the Source for a Pass. Last checked 4 August 2026. Apple Wallet and PassKit are trademarks of Apple Inc.; Cardr is not affiliated with Apple.
375 × 144 points for a store card or a coupon, and 375 × 98 points for an event ticket. Export at 1125 × 432 and 1125 × 294 respectively to cover @3x. The strip is the only large image on a pass that Wallet renders sharp rather than blurring, so it is the one worth doing properly.
No, in any form. Pass images are static PNG. APNG and animated GIF are not supported: Wallet shows a still frame or nothing at all. This trips people up because Google Wallet does support GIF, so advice written for one platform gets applied to the other. If you want a pass front that moves, there is no supported way to do it.
Because the style you chose does not display one. A store card and a coupon show a strip and no thumbnail; a generic pass shows a thumbnail and no strip; an event ticket shows one or the other but never both. Wallet fails silently here, which is the worst possible behaviour: the file is in the bundle, it is in the manifest, it is signed, and it renders nowhere.
Only with an NFC entitlement. The layout is requested with preferredStyleSchemes: ["posterEventTicket"] and it renders only for NFC-enabled passes signed with an NFC certificate, which Apple grants to transit, ticketing and access partners after a business review. It also requires one of semantics.venueName, venueRegionName or venueRoom. If you do not have the entitlement, the pass falls back to the standard layout rather than failing.
Fewer than the field count suggests, because the constraint is row width and not the number of slots. Wallet lays each row across roughly 345 points and truncates rather than wrapping. Measured at 15pt that is about 42 characters in a one-column row, 20 in a two-column row, 13 in three and 9 in four. A long email address in a four-column row does not shrink; it truncates, and so does everything beside it.
Ship @2x and @3x. @1x is only ever used by devices no current iPhone matches, and shipping it alone means every modern screen upscales a low-resolution file. There is no penalty for including all three beyond bundle size, and each one is hashed into the manifest and signed.
A ZIP archive containing pass.json, a manifest.json of SHA-1 hashes for every other file, a signature made with your Pass Type ID certificate, and the images the style requires. Miss the signature or sign with the wrong certificate and iOS refuses the file outright rather than rendering it badly. A boarding pass additionally fails validation without transitType.
No. It is our working notes, and it is generated from the module our own pass builder reads its rules out of, so it cannot drift from the code that obeys it. Every allotment and every limit is quoted from Apple's PassKit Package Format Reference, which is the authority and is linked here. Where we state something Apple does not document, we say so and say how we found it.
If you came here to make a pass for yourself rather than for a product, Cardr issues one in about a minute. Signed, on your phone, free forever.