How to Update Apple Passes with the PassNinja API

Daniel Baudino

Updated December 01, 2025

Overview

With the PassNinja API, Apple Wallet passes can be updated after creation or created as personalized passes (e.g., with a member ID or customer name). Updates keep fields current for balances, barcodes, and promotions.

This tutorial assumes you:

• Have a PassNinja account with API credentials
  
• Have already created passes using the PassNinja API
  
• Understand basic programming concepts and JSON formatting
  

Core principles of Apple pass updates

• More than 30 fields can be updated without reissuing the pass.
  
• Personalized and Updatable fields include:
  
  • Text fields (primary, secondary, auxiliary, back fields)
    
  • Barcodes
    
  • NFC payloads
    
  • Images (logo, strip, thumbnail)
    
  • Dates (relevant, expiration)
    
  • Personalization fields (member ID, name, tier)
    
• Updates should target dynamic data (balances, offers, promotions, personalization).
  

How to update the header and what to update

The header is the strip at the top of an Apple Wallet pass. It contains three elements:

• Logo (brand image)
  
• Logo text (brand name)
  
• Header fields (dynamic text values)
  

You should update the header fields, since they are always visible (even when the pass is collapsed). Use them for glanceable, real‑time information such as:

• Loyalty points balance
  
• Tier Level
  
• Event seat or entry code
  

Example updates:

• "POINTS: 1200" → "POINTS: 1500"
  
• "LEVEL: GOLD" → "LEVEL: PLATINUM"
  

Updating header fields ensures the pass reflects real‑time status without requiring the customer to expand it.

Here are the main API mapping for the header items:

brand.logo
brand.text
header.label
header.value

How to update colors and what to update

Apple Wallet passes support three main color properties:

• background Color: the pass background
  
• foreground Color: text and icons displayed on top of the background and value fields colors
• label Color (sometimes referred to as text.color): label labels
  

Best practices:

• Keep colors consistent with brand identity
  
• Use high contrast between background and foreground for readability
  
• Update colors only when reflecting campaigns, themes, or tier differentiation
  

Examples of updates:
- "background.color": "rgb(255,0,0)" → "background.color": "rgb(0,128,0)" (holiday campaign)
- "foreground.color": "rgb(255,255,255)" → "foreground.color": "rgb(0,0,0)" (improve contrast)
- "text.color": "rgb(200,200,200)" → "text.color": "rgb(50,50,50)" (better readability)

Updating colors helps align the pass with seasonal branding, promotions, or membership tiers while maintaining accessibility.

label.color
background.color
foreground.color

How to update the strip image and what to update

The strip image is the wide banner graphic below the header. It is one of the most visible elements of a pass and should be updated to reflect seasonal campaigns, limited‑time offers, or membership tiers.

The image must be self hosted on a secure HTTPS server (PassNinja only hosts static strip images).

Best practices:

• Use a CDN or stable hosting service with high availability.
  
• Keep file size optimized for fast loading.
  

Here is the main API mapping for the strip image:

strip.image

How to update the text fields and what to update

Primary, secondary, and auxiliary text fields are the main text areas on the front of an Apple Wallet pass.

• Primary field: headline data (e.g., name, flight number)
  
• Secondary fields: supporting details (e.g., seat assignment, member ID)
  
• Auxiliary fields: additional context (e.g., tier level, promo status)
  

Only update these fields with dynamic values that change over time. Examples:

• "Promotion: 20% discount" → "Promotion: 30% discount"
  
• "Seat 12A" → "Gate Changed: 14B"
  
• "Tier: Gold" → "Tier: Platinum"
  

These updates keep the pass aligned with the customer’s real‑time status and ensure the most important information is always visible, even in collapsed view.

Here is the main API mapping for the primary, secondary, and auxiliary text fields:

primary.label
primary.value
secondary.0.label
secondary.0.value
secondary.1.label
secondary.1.value
auxiliary.0.label
auxiliary.0.value
auxiliary.1.label
auxiliary.1.value
auxiliary.2.label
auxiliary.2.value

How to update the NFC payload and what to update

The NFC payload is the data transmitted when a customer taps their Apple Wallet pass against a compatible terminal. It enables contactless interactions for loyalty, access control, or promotions.

Update the NFC message. It must be:

• ≤ 64 bytes
  
• Concise and meaningful
  

Frequent updates are supported. PassNinja distributes the new payload so devices always have the latest version.

Here is the main API mapping for the NFC payload:

nfc.message

How to update the barcode and what to update

The barcode encodes a payload that can be scanned at POS, event gates, or access terminals. It is often the primary mechanism for validating a pass.

Update the barcode type or barcode message:

• Supported types: none, QR_Code, Code_128, PDF_417
  
• Payload: short, scannable string (e.g., loyalty ID, ticket code)
  

Examples of updates:

• Rotate payloads to prevent reuse (LOYALTY-12345 → LOYALTY-67890)
  
• Switch formats for compatibility (QR_Code → Code_128)
  
• Disable temporarily by setting type to none
  

Keeping the barcode current reduces fraud risk and ensures the pass remains scannable across different environments.

Here is the main API mapping for the barcode:

barcode.type
barcode.data
barcode.alt

How to update location-based data and what to update

Apple Wallet passes support location triggers so the pass surfaces when a customer is near a defined place. Each location can include:

• latitude: decimal degrees (required)
  
• longitude: decimal degrees (required)
  
• altitude: meters above sea level (optional)
  
• max.distance: radius in meters around the location (optional)
  
• relevant.text: short message shown on the lock screen when triggered (optional)
  

Update these fields when venue details change or when you want to adjust how and when the pass appears.

Examples of updates:

• Adjust location.latitude/location.longitude if a store relocates.
  
• Refine location.altitude for multi‑level venues (e.g., airport lounge, multistory buildings).
  
• Reduce location.distance in urban areas to avoid false triggers.
  
• Change location.message to highlight promotions or entry instructions.
  

Here is the main API mapping for location changes:

location.latitude
location.longitude
location.altitude
location.distance
location.message

How to update the back of the pass fields and what to update

Back of the pass fields appear when a customer flips the pass. They are used for reference information, not glanceable data. Typical content includes:

• Terms and conditions
  
• Customer service contacts
  
• Partner store locations
  
• FAQs or other reference details
  

These fields should be updated whenever supporting information changes (e.g., new phone number, updated terms, new partner locations). Unlike brand anchors (logo, org name), back fields are expected to evolve.

Examples of updates:

• "Customer Service: 1-800-555-1234" → "Customer Service: 1-800-555-5678"
  
• "Terms v1.0" → "Terms v2.0"
  
• "Partner Stores: 5" → "Partner Stores: 12"
  

Apple pass updates let you refresh these fields without reissuing the pass, ensuring customers always have the latest reference information.

Here is the main API mapping for the back of the pass fields:

backfield.label
backfield.value

How to update the relevant and expiration dates and what to update

Apple Wallet passes support two key date fields:

• relevant.date: timestamp that makes the pass surface on the lock screen near that time
  
• expiration.date: timestamp after which the pass is no longer valid
  

Update these fields to control visibility and lifecycle:

• Use relevant.date for event start times, promotion launches, or reminders
  
• Use expiration.date to remove expired tickets, coupons, or memberships
  

Examples of updates:

• "relevant.date": "2025-10-15T18:00:00Z" → "2025-10-16T18:00:00Z" (rescheduled event)
  
• "expiration.date": "2025-10-16T06:00:00Z" → "2025-10-20T06:00:00Z" (extended promotion)
  

Dynamic updates let you extend, reschedule, or renew passes without reissuing them.

Here is the main API mapping for the relevant and expiration dates:

relevant.date
expiration.date

How to create a pass

Passes can be created using the PassNinja API directly or through official modules available for different programming languages. Full details, including code examples and setup instructions, are provided in the PassNinja documentation: https://www.passninja.com/documentation.

Pass creation examples with PassNinja API mappings:

How to update a pass

Passes can be updated using the PassNinja API directly or through official modules available for different programming languages. Full details, including code examples and setup instructions, are provided in the PassNinja documentation: https://www.passninja.com/documentation.

Pass update examples with PassNinja API mappings:

What are the best practices for Apple pass updates

• Keep brand anchors stable

  • Logo, logo text, and brand colors should not change
    
  • Builds trust and recognition
    

• Focus updates on dynamic fields

  • Balances
    
  • Promotions
    
  • Barcodes
    
  • NFC payloads
    
  • Dates (relevant and expiration)
    

• Improve security

  • Rotate barcodes
    
  • Rotate NFC payloads
    

• Enhance engagement

  • Use relevant text to surface passes at the right time
    
  • Keep dates accurate so passes appear/disappear when expected
    

Making NFC easy with PassNinja

PassNinja simplifies the process of creating and distributing NFC enabled wallet passes. By combining a visual dashboard with flexible REST APIs and SDKs in multiple languages, it allows you to design, deploy, and update passes quickly. Most importantly, PassNinja provides the Apple NFC entitlement out of the box, eliminating the lengthy approval process and red tape typically required to enable NFC functionality on Apple Wallet passes.

Developers can set an initial NFC message when creating a pass and then update it through Apple pass updates as customer status changes. This makes it easy to deliver personalized tap experiences without reissuing passes. Because NFC payloads are lightweight, they can be updated frequently to reflect promotions, tier upgrades, or access permissions. PassNinja handles the complexity of distributing these updates to devices, ensuring that customers always have the latest experience at their fingertips.

Conclusion

Apple pass updates transform wallet passes from static cards into living experiences. By carefully choosing which fields to update and which to keep stable, you can deliver both trust and freshness. PassNinja provides the tools to manage this balance effectively, ensuring that your passes remain timely, secure, and engaging. Whether you are updating balances, rotating barcodes, or refreshing NFC payloads, Apple pass updates keep your passes relevant and valuable.