Introduction
When updating a pass via the PassKit API, there is a strict 10,000-byte (10KB) limit for the content being sent. If your request exceeds this limit, the API will reject it.
Why is there a Limit?
The 10,000-byte limit for sending updated content to a wallet passes exists for several technical and practical reasons:
Bandwidth & Performance Optimization
Wallet passes are designed to be lightweight for quick loading, especially when refreshed on a user's device.
A smaller payload ensures faster transmission over mobile networks, reducing latency when updating passes.
Device Storage & Memory Constraints
Wallet apps need to store multiple passes locally on a user's device.
Enforcing a size limit prevents excessive storage usage, which could slow down the device or the wallet app.
Push Notification Payload Limits
Updates to wallet passes are often delivered via push notifications (APNs for Apple Wallet, FCM for Google Pay).
These services have payload size limits (e.g., APNs historically had a 4KB limit, though now it's larger). Keeping pass updates small ensures compatibility.
Security & Stability
Large payloads could be exploited for denial-of-service (DoS) attacks or cause crashes in wallet apps.
A strict limit ensures predictable behavior and prevents abuse.
User Experience (UX) Considerations
Wallet passes are meant to be glanceable—excessive data could make them cluttered or slow to render.
The limit encourages developers to send only essential updates (e.g., changing a boarding pass status rather than embedding full details every time).
What Happens If You Exceed the Limit?
The API will return an error, and the update will fail.
Do not repeatedly retry the same request—this can trigger rate limits and may result in account suspension.
Instead, handle the error gracefully by reducing the payload size before retrying.
Best Practices to Reduce Pass Content Size
Optimize Images
Use compressed images (JPEG for photos, PNG for graphics with transparency).
Resize images to the exact dimensions needed in the pass (e.g., logo, thumbnail). For details, refer to Optimizing Images.
Avoid embedding high-resolution images when smaller ones will suffice.
Minimize Text Content
Avoid long lists (e.g., listing hundreds of store locations). Instead:
Link to a mobile-optimized web page (e.g., a store locator).
Example: Burger King doesn’t list every location on their coupon pass—they link to a website where users can search for nearby stores.
Use abbreviations where possible (e.g., "St" instead of "Street").
Remove Unnecessary Fields
Only include essential data in the pass.
While the back of the pass allows for a lot of content, think about how you would design a physical card or coupon—would you cram in paragraphs of text or a long list of locations? Probably not.
Less is more—scrolling through excessive content on the back of a pass creates a poor user experience.
Link to a mobile-friendly webpage or app instead of overloading the pass with details.
Handling API Rejections
If your request is rejected due to size limits:
Do not retry immediately—this can lead to rate limiting and may result in account suspension.
Analyze the payload and reduce its size using the techniques above.
Implement error handling in your code to alert you when payloads are too large.
Conclusion
By following these best practices, you can ensure smooth pass updates and avoid disruptions to your service.