Time-Based Surfacing Reference
Updated March 26, 2026
TL;DR: How to trigger time-based lock screen surfacing for wallet passes.
- Apple: Uses `relevant.date` for passive lock screen surfacing
- Google: Each pass type uses different fields (`dateTime.start` or `validTimeInterval`)
- Apple timing window is undocumented; Google sends 3-24 hours before depending on pass type
- Google supports automatic expiry reminders (48 hours before)
- Apple only supports Event Ticket and Access Control pass types
Overview
This reference covers time-based pass surfacing for Apple Wallet and Google Wallet. When the relevant time approaches, passes automatically appear on the lock screen or trigger notifications.
Quick Reference
| Spec | Apple Wallet | Google Wallet |
|---|---|---|
| Field | relevant.date | Varies by pass type (see below) |
| Dates allowed | 1 per pass | Start + End range |
| Behavior | Passive (lock screen surfacing) | Active (push notification) |
| Timing window | Undocumented ("within a few hours") | Fixed (3-24 hours by pass type) |
| Expiry reminder | None (manual via update) | 48 hours automatic |
| Pass type restrictions | Event Ticket / Access Control only | Event Ticket / Access Control |
Apple Wallet
How It Works
- Pass includes
relevant.datetimestamp - Device monitors proximity to that date/time
- When user is "close enough" to the date, pass surfaces on lock screen
- User sees the pass card — no notification text
This is passive lock screen surfacing, not a push notification. The pass appears automatically based on time proximity.
Limits
| Limit | Value |
|---|---|
| Relevant dates per pass | 1 |
| Timing window | Undocumented (Apple-controlled) |
Pass Type Support
| Pass Type | Support | Behavior |
|---|---|---|
| Event Ticket | Yes | Date alone works |
| Access Control | Yes | Date alone works; location optional |
| Loyalty | No | N/A |
| Coupon | No | N/A |
Timing Window Behavior
Apple does not document exact timing windows. The system calculates "close enough" based on pass style:
| Pass Type | Estimated Window |
|---|---|
| Event Ticket | Hours before event |
| Access Control | Hours before date |
relevant.dateshould not be interpreted as the exact moment of an event, but as "an arbitrary date marker for the system to highlight relevance within a few hours."
relevant.date vs expiration.date
| Field | Purpose | Lock Screen | Pass State |
|---|---|---|---|
relevant.date | When pass surfaces | Controls surfacing | No effect |
expiration.date | When pass expires | No effect | Moves to "Expired Passes" |
User Requirements
| Requirement | Setting |
|---|---|
| Location Services | Enabled (if location-based) |
| Wallet location access | Enabled |
| "Suggest on Lock Screen" | Enabled (per-pass setting) |
Google Wallet
How It Works by Pass Type
Each Google Wallet pass type uses different fields and timing for automatic notifications:
| Pass Type | Time Field | Notification Timing | Notification Text | Auto-Dismiss |
|---|---|---|---|---|
| Event Ticket | dateTime.start | 3 hours before | "[eventName]" | 60 min after start |
| Access Control | validTimeInterval.start | 24 hours before | "[cardTitle] is available now" | Based on validTimeInterval.end |
Google sends active push notifications, not passive surfacing. Users must have "Updates about your passes" enabled in Settings > Notifications.
Expiry Notifications
All pass types with a validTimeInterval.end support automatic expiry notifications:
| Timing | Notification Text | Customizable |
|---|---|---|
| 48 hours before end | "[cardTitle] expires in [x] days" | No |
Multiple Passes Behavior
When users have multiple passes, only the soonest usable pass is shown in the notification. For grouped passes, tapping the notification allows users to swipe through the complete group.
Notification Pinning
All automatic notifications are pinned and won't auto-dismiss when opened by the user. They remain until the auto-dismiss time is reached.
Rate Limits
| Limit | Value |
|---|---|
| Notifications per 24 hours | 3 per pass (enforced) |
| Exceeding limit | QuotaExceededException |
Platform Comparison
Surfacing Behavior
| Aspect | Apple Wallet | Google Wallet |
|---|---|---|
| Type | Passive (lock screen card) | Active (push notification) |
| User action required | Swipe to open | Tap notification |
| Custom text | No | No (Google-controlled) |
| Timing control | None (Apple-controlled) | Fixed intervals by pass type |
Timing Specifications
| Pass Type | Apple Timing | Google Timing | Google Field |
|---|---|---|---|
| Event Ticket | Undocumented | 3 hours before | dateTime.start |
| Access Control | Undocumented | 24 hours before | validTimeInterval.start |
| Expiry reminder | Not automatic | 48 hours before | validTimeInterval.end |
Pass Type Support
| Pass Type | Apple | |
|---|---|---|
| Event Ticket | Yes | Yes |
| Access Control | Yes | Yes |
| Loyalty | No | No (no automatic time-based) |
| Coupon | No | No (no automatic time-based) |
Common Mistakes
Using relevant.date for Loyalty passes (Apple) — Not supported; pass won't surface
Omitting timezone in relevant.date (Apple) — Defaults to UTC, causing wrong timing
Expecting custom notification text (Google) — Google controls all notification content
Relying on exact timing (Apple) — Timing window is undocumented and variable
Exceeding 3 notifications/day (Google) — Results in
QuotaExceededExceptionUsing relevant.date as expiration (Apple) — Known iOS bug; use
expiration.dateseparatelyForgetting timezone differences — Multi-timezone events need careful timestamp handling