Guide

The .pkpass file format explained

Behind every Apple Wallet pass is a .pkpass file: a signed package with a JSON description of the pass, its images, a manifest and a signature. This guide walks through each part, how passes are packaged and served, and how they update after they’ve been added - useful whether you’re building passes yourself or choosing a tool that builds them for you.

Last updated October 9, 2026. Facts about Apple Wallet and Google Wallet were checked against Apple’s and Google’s own documentation, linked in the sources.

The short answer

A .pkpass file is a ZIP archive containing pass.json (the pass’s data), image files, manifest.json (a SHA-1 hash of every file) and a signature file (a PKCS #7 signature of the manifest, made with the issuer’s Pass Type ID certificate). Wallet checks the signature and hashes before it accepts the pass.

The files in a pass

pass.json

pass.json is a single JSON object describing the pass. A minimal example for a store card:

{
  "formatVersion": 1,
  "passTypeIdentifier": "pass.com.example.loyalty",
  "teamIdentifier": "ABCDE12345",
  "serialNumber": "member-0042",
  "organizationName": "Example Coffee",
  "description": "Example Coffee loyalty card",
  "backgroundColor": "rgb(28, 17, 71)",
  "foregroundColor": "rgb(255, 255, 255)",
  "storeCard": {
    "primaryFields": [{ "key": "points", "label": "Points", "value": 120 }]
  },
  "barcodes": [
    { "format": "PKBarcodeFormatQR", "message": "member-0042", "messageEncoding": "iso-8859-1" }
  ]
}

Required keys

• formatVersion - always 1.
• passTypeIdentifier and teamIdentifier - from the Apple Developer account that signs the pass.
• serialNumber - unique for each pass of that type; it’s how updates find the right pass.
• organizationName and description - shown to users and used by accessibility features.
• One style key - boardingPass, coupon, eventTicket, generic or storeCard - holding the header, primary, secondary, auxiliary and back fields.

Common optional keys

• barcodes - the code to scan: QR, PDF417, Aztec or Code 128.
• backgroundColor, foregroundColor, labelColor - the pass’s colors.
• relevantDate, locations and beacons - when and where the pass is relevant.
• expirationDate and voided - mark a pass as no longer valid.
• webServiceURL and authenticationToken - enable updates (see below).

Images

Images are PNG files with fixed names, supplied at standard, @2x and @3x resolutions, for example logo.png, logo@2x.png and logo@3x.png. Which images a pass can use depends on its style: strip images appear on coupons, store cards and event tickets; thumbnails on generic passes and event tickets; background images on event tickets; footer images on boarding passes.

For recommended sizes and design rules, see our wallet pass best practices guide.

manifest.json

manifest.json maps every file in the package (except itself and the signature) to the SHA-1 hash of its contents:

{
  "pass.json": "3f0c…a91e",
  "icon.png": "8b2d…04f7",
  "icon@2x.png": "c41a…9e20",
  "logo.png": "e7d9…1b33"
}

If any file changes, its hash no longer matches and Wallet rejects the pass. That’s why you can’t edit a .pkpass file by hand: you have to rebuild the manifest and sign again.

The signature

The signature file is a detached PKCS #7 signature of manifest.json, made with the private key of a Pass Type ID certificate and including Apple’s WWDR intermediate certificate. To sign passes yourself you need:

• An Apple Developer Program membership.
• A Pass Type ID registered in that account, and its signing certificate.
• Apple’s current WWDR intermediate certificate.

Packaging and serving

1. Zip the files with everything at the top level of the archive - no enclosing folder.
2. Name it with the .pkpass extension.
3. Serve it with the file type application/vnd.apple.pkpass, so Safari opens Wallet instead of downloading a ZIP.

To deliver several passes at once, bundle them as a .pkpasses file, served as application/vnd.apple.pkpasses.

How passes update

A pass with a webServiceURL and authenticationToken can be updated after it’s been added:

1. When the pass is added, the device registers with your web service.
2. When the pass changes, you send that device a push notification through Apple.
3. The device asks your service which passes changed, then downloads the new versions.
4. When the pass is deleted, the device unregisters.

Apple notes that updates aren’t guaranteed - for example, if the phone is offline or the user turned updates off for that pass.

How Google Wallet differs

Google Wallet doesn’t use files. A Google Wallet pass is a class (the shared design) and an object (one person’s pass) created through Google’s Wallet API, and saved with an “Add to Google Wallet” link carrying a signed JSON Web Token. Updates are made by changing the object through the API. To reach both iPhone and Android, an issuer maintains both formats.

Just want to open a pass someone sent you? See what a .pkpass file is and how to open one.

Frequently asked questions

Sources

Apple’s newer developer pages load dynamically, so where a number comes from Apple it is taken from its Wallet Developer Guide and support pages. If Apple’s or Google’s current documentation differs, follow theirs.

• Apple: Wallet Passes documentation
• Apple: Wallet Passes, Building a pass
• Apple: Wallet Passes, Creating the source for a pass
• Apple: Wallet Passes, Pass (pass.json keys)
• Apple: Wallet Passes, Adding a web service to update passes
• Google: Working with JSON Web Tokens (JWT)