Pass Designer: What It Is and How Apple’s Wallet Beta Works

⏱️ Reading time: 12 min

Apple opened the beta for Pass Designer, a new app that turns creating a Wallet pass into dragging fields and picking colors instead of writing JSON by hand. Before this, any coffee shop, airline, or venue that wanted to issue a loyalty card or digital ticket had to build the pass.json file directly or pay for a third-party tool.

The core promise is visual fidelity: the official Pass Designer page explains that the preview uses the same renderer as iOS and watchOS, so what you see in the desktop app is exactly what the end user receives on their iPhone or Apple Watch.

TL;DR

• Pass Designer is Apple’s beta app for creating and previewing Wallet passes without writing JSON by hand.
• The preview uses the same rendering engine as iOS and watchOS, so what you see is what the user sees.
• Semantic tags add structured data that activates Siri Suggestions, Calendar, and Maps.
• Real-time validation flags missing required keys before exporting the pass.
• Requires macOS 27 and an Apple Developer account to download.

What Is Pass Designer?

Pass Designer is Apple’s official macOS application for creating, editing, and previewing Apple Wallet passes without writing code: it defines colors, fields, barcodes, and semantic tags for loyalty cards, event tickets, coupons, and boarding passes.

Under the hood, every pass is still a pass.json file compressed together with its images into a .pkpass. The app doesn’t invent a new format: it exposes, through a graphical interface, the same schema Apple has documented at Wallet Passes for more than a decade, but validates each field as you edit it.

Why the Apple Wallet Editor Matters

Until now, designing a pass involved two separate roles: someone to assemble the JSON with the correct fields, and someone to check that the colors and logo looked right on screen. A typo in a required key, such as passTypeIdentifier, would only break the pass once you tried to open it on a real iPhone.

The Apple Wallet editor eliminates that trial-and-error cycle. Since the preview renders with the same engine as iOS, a designer with no knowledge of JSON can adjust the layout, test color contrast, and check how the pass looks on an Apple Watch, all before touching a single line of code.

How the Pass-Creation App Works

Templates and Colors

The app starts with templates provided by Apple for each type of pass: boarding pass, coupon, event ticket, store card, and generic pass. From there, you separately adjust the background color, the foreground color, and the label color (labels), the three parameters that define the brand’s visual identity inside Wallet.

Real-Time Preview

Every change is reflected instantly in two parallel previews, one for iPhone and one for Apple Watch. This matters because the available space on the watch screen is much smaller, and a field that reads well on the phone can get cut off on the wrist if it isn’t designed with both sizes in mind from the start.

The pass.json Format Behind the Wallet Card Designer

Every pass, whether edited by hand or with the app, ends up being the same type of file. A minimal pass.json for a loyalty card looks like this:

{
  "formatVersion": 1,
  "passTypeIdentifier": "pass.org.programacion.cafeteria",
  "serialNumber": "CAFE-00142",
  "teamIdentifier": "A1B2C3D4E5",
  "organizationName": "Cafeteria El Solitario",
  "description": "Loyalty card",
  "storeCard": {
    "primaryFields": [
      { "key": "balance", "label": "STAMPS", "value": "7 of 10" }
    ]
  },
  "backgroundColor": "rgb(60, 30, 10)",
  "foregroundColor": "rgb(255, 255, 255)"
}

This JSON defines a stamp card with a dark brown background and white text. The app validates on the fly that passTypeIdentifier and teamIdentifier match a real certificate before letting you export the pass; if either is missing, it flags the field in red instead of generating a broken file.

Semantic Tags: Data That Siri and Maps Understand

For event tickets and boarding passes, semantic tags add a layer of structured data on top of the visible fields. An event ticket with semantic tags looks the same on screen, but it also lets Siri suggest it ahead of the event’s start time and lets Maps offer directions to the venue without the user opening Wallet:

{
  "eventTicket": {
    "primaryFields": [
      { "key": "event", "label": "EVENT", "value": "Konfa Dev LATAM 2026" }
    ]
  },
  "semantics": {
    "eventName": "Konfa Dev LATAM 2026",
    "venueName": "Centro de Convenciones San Salvador",
    "eventStartDate": "2026-11-14T18:00-06:00"
  }
}

The pass-creation app can also automatically generate a version of the pass without the semantics block, so it keeps working on older versions of Wallet that ignore that key instead of breaking because of it.

Practical Examples With the Pass Design Tool

Consider three real scenarios. A coffee chain needs a simple stamp card: ten identical fields, a counter, and a corporate color, the most basic case of storeCard. An airline needs a boarding pass with a barcode, gate, and flight semantic data so the system can notify the user when check-in is about to close.

A music venue, on the other hand, needs event tickets with eventStartDate and venueName so the pass automatically shows up on the lock screen on the day of the show. All three cases share the same base pass.json schema; what changes is which top-level block is used (storeCard, boardingPass, or eventTicket) and which semantic tags make sense for that type of pass.

Getting Started: Create a pass.json Without the Wallet Card Designer

To follow this section you need an Apple Developer account (the free tier is enough to generate a Pass Type ID certificate), the Apple WWDR intermediate certificate, and openssl plus zip installed (they come by default on macOS and on most Linux distros; on Windows, PowerShell doesn’t ship with openssl, so you need to install it with winget install ShiningLight.OpenSSL.Light and use Compress-Archive instead of zip).

With the pass.json and the images (icon.png, [email protected], logo.png) in a folder, the manual process has four steps:

# 1. validate that the JSON is correct
plutil -lint pass.json

# 2. separate the certificate and private key from the .p12 exported from Keychain Access
openssl pkcs12 -in Certificates.p12 -clcerts -nokeys -out passcertificate.pem
openssl pkcs12 -in Certificates.p12 -nocerts -nodes -out passkey.pem

# 3. generate manifest.json with the SHA-1 hash of each file
shasum -a 1 pass.json icon.png [email protected] logo.png > manifest.txt
python3 -c "import json; print(json.dumps({l.split()[1]: l.split()[0] for l in open('manifest.txt')}))" > manifest.json

# 4. sign the manifest with the certificate and the WWDR
openssl smime -binary -sign -certfile AppleWWDRCA.pem \
  -signer passcertificate.pem -inkey passkey.pem \
  -in manifest.json -out signature -outform DER

# 5. package the .pkpass
zip -r cafeteria.pkpass pass.json manifest.json signature icon.png [email protected] logo.png

The zip command from the last step prints something like this, confirming that the six files ended up inside the package:

  adding: pass.json (deflated 51%)
  adding: manifest.json (deflated 40%)
  adding: signature (stored 0%)
  adding: icon.png (stored 0%)
  adding: [email protected] (stored 0%)
  adding: logo.png (deflated 2%)

To confirm the JSON is valid before signing anything, plutil -lint pass.json returns pass.json: OK if the syntax is well-formed; any other message points to the exact line of the error.

💡 Tip: run plutil -lint pass.json before signing and zipping. It’s faster to catch an extra comma there than after Wallet rejects the .pkpass without explaining why.

flowchart LR
    A["Choose template"] --> B["Edit fields and colors"]
    B --> C["Add semantic tags"]
    C --> D["Preview on iOS and watchOS"]
    D --> E["Automatic validation"]
    E --> F["Export pass.json or .pkpass"]

Real Use Cases for the Apple Wallet Editor

• Loyalty cards, coffee chains or retailers with a stamp counter that increases every time the pass is updated from the server.
• Boarding passes, airlines that need gate, seat, and barcode, with flight semantic data for automatic notifications.
• Event tickets, venues that want the pass to appear on the lock screen near the time and location of the show.
• Coupons, businesses with a temporary offer, where the relevantDate field makes the pass stand out automatically only while the promotion is active.

Common Mistakes When Using the Pass-Creation App

• Mismatched teamIdentifier, if it doesn’t exactly match the certificate’s Team ID, Wallet rejects the pass without a clear error message.
• Color contrast, setting foregroundColor and backgroundColor to nearly identical values makes the text unreadable on screens with low brightness.
• Wrong barcode format, mixing PKBarcodeFormatQR with a scanner that only accepts PDF417 causes the scan to fail at the point of sale.
• Duplicate serialNumber, two passes with the same serial number for the same passTypeIdentifier overwrite each other on the user’s device.
• webServiceURL without authenticationToken, declaring the update URL without the required token prevents the server from receiving requests from Wallet.

Comparison: Pass Designer vs. Manual JSON Editing

Deep Dive: This Is How PassKit Designer Validates Semantic Tags

When Wallet opens a .pkpass, it first decompresses the file and recalculates the SHA-1 hash of every item listed in manifest.json. If a single byte of pass.json or an image changed after signing, the hash won’t match and the device silently rejects the entire pass without installing it.

The signature itself doesn’t protect the content from being read, it only guarantees integrity: anyone can open a .pkpass with a file decompressor and read the JSON inside. What the signature prevents is someone modifying a legitimate pass after it left the server without Wallet detecting it.

For passes that change over time, such as a boarding pass that updates the departure gate, the pass declares a webServiceURL and an authenticationToken. When the server has an update, it triggers a silent push via APNs; Wallet receives that push and requests the new version of the pass from the server, without the user having to do anything:

sequenceDiagram
    participant U as User
    participant W as Apple Wallet
    participant S as Pass server
    participant A as APNs
    U->>W: adds the pass to Wallet
    W->>S: registers the device token
    S-->>A: update push
    A-->>W: notifies that a change is available
    W->>S: requests the updated pass
    S-->>W: responds with new pass.json
    Note over U,W: the pass updates without reopening the app

The five pass types supported by PassKit (boarding pass, coupon, event ticket, store card, and generic) share exactly this same signing and update cycle; the only thing that changes between them is which visible fields and which semantic tags make sense to declare:

flowchart TD
    A["PassKit: pass types"] --> B["Boarding Pass"]
    A --> C["Coupon"]
    A --> D["Event Ticket"]
    A --> E["Store Card"]
    A --> F["Generic"]

⚠️ Heads up: this editor’s beta only installs on macOS 27. If your machine is on an earlier version, there’s no way to try it today other than writing the pass.json by hand.

Your next step: write a pass.json for a simple loyalty card, run plutil -lint pass.json to confirm it’s valid, and sign it with the openssl commands from the previous section.

Frequently Asked Questions

Is Pass Designer free?

Yes, it downloads at no cost with an Apple Developer account, but it only installs on macOS 27 for as long as the beta lasts.

What do the semantic tags added by the Wallet card designer bring?

They turn plain-text fields into structured data that Siri, Calendar, and Maps can read directly, enabling suggestions and directions without the user opening Wallet.

Do I need PassKit Designer to generate passes from a backend?

No. For bulk or dynamic generation, a library like passkit-generator in Node.js is a better fit, since it signs and packages the .pkpass files programmatically.

What happens if the Apple Wallet editor flags a field in red?

It indicates a missing or invalid required key, such as passTypeIdentifier or teamIdentifier; the pass can’t be exported until it’s fixed.

Do passes created with the pass-creation app work on Apple Watch?

Yes, the preview includes the Apple Watch layout from the start, with the same rendering engine that watchOS uses.

References

• Apple Developer: Pass Designer: official beta page, requirements, and download.
• Apple Developer: Wallet Passes: complete reference for the pass.json format and semantic keys.
• Wikipedia: Apple Wallet: history and evolution of Apple’s app for passes and cards.
• GitHub: passkit-generator: open source Node.js library for generating and signing .pkpass files.

📱 Enjoying this content? Follow @programacion on Telegram for daily tech content in Spanish: quick summaries, fresh content every day.

Featured image: Foto de Logan Voss en Unsplash