Apple Parameters

Parameters organized by pass type. Each pass type has different image and field capabilities.

Note: These API parameters represent the default field names. You can customize field names and configure which fields are available for your pass template using the Pass Dashboard.
Coupon

For discounts, offers, and promotional passes. Supports strip image.

Appearance
brand.logo file image (png) path: logo

The logo image displayed at the top of the pass. Recommended size: 160x50px @1x.

brand.text string path: logoText

Text displayed next to or below the logo. Typically the organization name.

label.color string path: labelColor

Color used for field labels. Accepts hex color codes or rgb() values.

background.color string path: backgroundColor

Background color of the pass. Accepts hex color codes or rgb() values.

foreground.color string path: foregroundColor

Color used for field values and other text. Accepts hex color codes or rgb() values.

icon.link file image (png) path: icon

The pass icon shown in notifications and on the lock screen. Required size: 29x29px @1x.

strip.image file image (png) path: stripImage

A strip image displayed behind the primary fields. Recommended size: 375x144px @1x (760x294px @2x).

Header Fields
header.label string path: coupon.headerFields.0.label

Label text displayed above the header field value.

header.value string path: coupon.headerFields.0.value

Value displayed in the header field, shown at the top right of the pass.

Primary Fields
primary.label string path: coupon.primaryFields.0.label

Label text for the primary field. Often used for the offer description.

primary.value string path: coupon.primaryFields.0.value

The main content displayed prominently on the pass. Typically the discount or offer amount.

Secondary Fields
secondary.0.label string path: coupon.secondaryFields.0.label

Label for the first secondary field.

secondary.0.value string path: coupon.secondaryFields.0.value

Value for the first secondary field.

secondary.1.label string path: coupon.secondaryFields.1.label

Label for the second secondary field.

secondary.1.value string path: coupon.secondaryFields.1.value

Value for the second secondary field.

Auxiliary Fields
auxiliary.0.label string path: coupon.auxiliaryFields.0.label

Label for the first auxiliary field.

auxiliary.0.value string path: coupon.auxiliaryFields.0.value

Value for the first auxiliary field.

auxiliary.1.label string path: coupon.auxiliaryFields.1.label

Label for the second auxiliary field.

auxiliary.1.value string path: coupon.auxiliaryFields.1.value

Value for the second auxiliary field.

auxiliary.2.label string path: coupon.auxiliaryFields.2.label

Label for the third auxiliary field.

auxiliary.2.value string path: coupon.auxiliaryFields.2.value

Value for the third auxiliary field.

Back Fields
back.label string path: coupon.backFields.0.label

Label for the back field, shown when the pass is flipped.

back.value string path: coupon.backFields.0.attributedValue

Value for the back field. Supports data detectors for links, phone numbers, addresses, and calendar events.

Barcode
barcode.alt string path: barcode.altText

Alternative text displayed below the barcode for manual entry.

barcode.data string path: barcode.message

The data encoded in the barcode. This value is scanned by barcode readers.

barcode.type enum<string> path: barcode.format

The barcode format to display on the pass.

Available options:

  • PKBarcodeFormatQR (2D square barcode, high data capacity)
  • PKBarcodeFormatPDF417 (2D stacked barcode, used for IDs and transport)
  • PKBarcodeFormatCode128 (1D barcode for alphanumeric data)
NFC
nfc.message string path: nfc.message

The message transmitted when the pass is tapped on an NFC reader. Maximum 64 bytes.

Locations
location.latitude string path: locations.0.latitude

Latitude coordinate for the location-based notification trigger.

location.longitude string path: locations.0.longitude

Longitude coordinate for the location-based notification trigger.

location.message string path: locations.0.relevantText

Message displayed when the user is near the location.

Dates
relevant.date datetime path: relevantDate

Date and time when the pass becomes relevant. The pass appears on the lock screen near this time. Format: ISO 8601.

expiration.date datetime path: expirationDate

Date and time when the pass expires. After this time, the pass is marked as expired. Format: ISO 8601.

Loyalty

For membership cards, rewards programs, and store cards. Supports strip image.

Appearance
brand.logo file image (png) path: logo

The logo image displayed at the top of the pass. Recommended size: 160x50px @1x.

brand.text string path: logoText

Text displayed next to or below the logo. Typically the organization name.

label.color string path: labelColor

Color used for field labels. Accepts hex color codes or rgb() values.

background.color string path: backgroundColor

Background color of the pass. Accepts hex color codes or rgb() values.

foreground.color string path: foregroundColor

Color used for field values and other text. Accepts hex color codes or rgb() values.

icon.link file image (png) path: icon

The pass icon shown in notifications and on the lock screen. Required size: 29x29px @1x.

strip.image file image (png) path: stripImage

A strip image displayed behind the primary fields. Recommended size: 375x144px @1x (760x294px @2x).

Header Fields
header.label string path: storeCard.headerFields.0.label

Label text displayed above the header field value.

header.value string path: storeCard.headerFields.0.value

Value displayed in the header field, shown at the top right of the pass. Often used for membership tier.

Primary Fields
primary.label string path: storeCard.primaryFields.0.label

Label text for the primary field.

primary.value string path: storeCard.primaryFields.0.value

The main content displayed prominently on the pass. Typically the member's name.

Secondary Fields
secondary.0.label string path: storeCard.secondaryFields.0.label

Label for the first secondary field.

secondary.0.value string path: storeCard.secondaryFields.0.value

Value for the first secondary field.

secondary.1.label string path: storeCard.secondaryFields.1.label

Label for the second secondary field.

secondary.1.value string path: storeCard.secondaryFields.1.value

Value for the second secondary field.

Auxiliary Fields
auxiliary.0.label string path: storeCard.auxiliaryFields.0.label

Label for the first auxiliary field.

auxiliary.0.value string path: storeCard.auxiliaryFields.0.value

Value for the first auxiliary field.

auxiliary.1.label string path: storeCard.auxiliaryFields.1.label

Label for the second auxiliary field.

auxiliary.1.value string path: storeCard.auxiliaryFields.1.value

Value for the second auxiliary field.

auxiliary.2.label string path: storeCard.auxiliaryFields.2.label

Label for the third auxiliary field.

auxiliary.2.value string path: storeCard.auxiliaryFields.2.value

Value for the third auxiliary field.

Back Fields
back.label string path: storeCard.backFields.0.label

Label for the back field, shown when the pass is flipped.

back.value string path: storeCard.backFields.0.attributedValue

Value for the back field. Supports data detectors for links, phone numbers, addresses, and calendar events.

Barcode
barcode.alt string path: barcode.altText

Alternative text displayed below the barcode for manual entry.

barcode.data string path: barcode.message

The data encoded in the barcode. This value is scanned by barcode readers.

barcode.type enum<string> path: barcode.format

The barcode format to display on the pass.

Available options:

  • PKBarcodeFormatQR (2D square barcode, high data capacity)
  • PKBarcodeFormatPDF417 (2D stacked barcode, used for IDs and transport)
  • PKBarcodeFormatCode128 (1D barcode for alphanumeric data)
NFC
nfc.message string path: nfc.message

The message transmitted when the pass is tapped on an NFC reader. Maximum 64 bytes.

Locations
location.latitude string path: locations.0.latitude

Latitude coordinate for the location-based notification trigger.

location.longitude string path: locations.0.longitude

Longitude coordinate for the location-based notification trigger.

location.message string path: locations.0.relevantText

Message displayed when the user is near the location.

Dates
relevant.date datetime path: relevantDate

Date and time when the pass becomes relevant. The pass appears on the lock screen near this time. Format: ISO 8601.

expiration.date datetime path: expirationDate

Date and time when the pass expires. After this time, the pass is marked as expired. Format: ISO 8601.

Event Ticket

For concerts, sports events, movies, and flights.

Basic Event Ticket

Standard event ticket. Supports strip, thumbnail, and background images.

Appearance
brand.logo file image (png) path: logo

The logo image displayed at the top of the pass. Recommended size: 160x50px @1x.

brand.text string path: logoText

Text displayed next to or below the logo. Typically the event organizer or venue name.

label.color string path: labelColor

Color used for field labels. Accepts hex color codes or rgb() values.

background.color string path: backgroundColor

Background color of the pass. Accepts hex color codes or rgb() values.

foreground.color string path: foregroundColor

Color used for field values and other text. Accepts hex color codes or rgb() values.

icon.link file image (png) path: icon

The pass icon shown in notifications and on the lock screen. Required size: 29x29px @1x.

strip.image file image (png) path: stripImage

A strip image displayed behind the primary fields. Recommended size: 375x98px @1x for event tickets.

thumbnail.image file image (png) Event Ticket only path: thumbnailImage

A thumbnail image displayed on the right side of the pass. Recommended size: 90x90px @1x (270x270px @3x). Typically used for artist/performer photos or event logos.

background.image file image (png) Event Ticket only path: backgroundImage

Background image for the pass. The image is blurred and used as a backdrop behind the pass content. Recommended size: 180x220px @1x.

Header Fields
header.label string path: eventTicket.headerFields.0.label

Label text displayed above the header field value.

header.value string path: eventTicket.headerFields.0.value

Value displayed in the header field, shown at the top right of the pass.

Primary Fields
primary.label string path: eventTicket.primaryFields.0.label

Label text for the primary field.

primary.value string path: eventTicket.primaryFields.0.value

The main content displayed prominently on the pass. Typically the event name or title.

Secondary Fields
secondary.0.label string path: eventTicket.secondaryFields.0.label

Label for the first secondary field.

secondary.0.value string path: eventTicket.secondaryFields.0.value

Value for the first secondary field.

secondary.1.label string path: eventTicket.secondaryFields.1.label

Label for the second secondary field.

secondary.1.value string path: eventTicket.secondaryFields.1.value

Value for the second secondary field.

Auxiliary Fields
auxiliary.0.label string path: eventTicket.auxiliaryFields.0.label

Label for the first auxiliary field.

auxiliary.0.value string path: eventTicket.auxiliaryFields.0.value

Value for the first auxiliary field.

auxiliary.1.label string path: eventTicket.auxiliaryFields.1.label

Label for the second auxiliary field.

auxiliary.1.value string path: eventTicket.auxiliaryFields.1.value

Value for the second auxiliary field.

auxiliary.2.label string path: eventTicket.auxiliaryFields.2.label

Label for the third auxiliary field.

auxiliary.2.value string path: eventTicket.auxiliaryFields.2.value

Value for the third auxiliary field.

auxiliary.3.label string default: Row

Label for the fourth auxiliary field.

auxiliary.3.value string default: 1

Value for the fourth auxiliary field.

auxiliary.4.label string default: Seat

Label for the fifth auxiliary field.

auxiliary.4.value string default: 1

Value for the fifth auxiliary field.

Back Fields
backfield.0.label string path: eventTicket.backFields.0.label

Label for the back field, shown when the pass is flipped.

backfield.0.value string path: eventTicket.backFields.0.attributedValue

Value for the back field. Supports data detectors for links, phone numbers, addresses, and calendar events.

Barcode
barcode.alt string path: barcode.altText

Alternative text displayed below the barcode for manual entry.

barcode.data string path: barcode.message

The data encoded in the barcode. This value is scanned by barcode readers.

barcode.type enum<string> path: barcode.format

The barcode format to display on the pass.

Available options:

  • PKBarcodeFormatQR (2D square barcode, high data capacity)
  • PKBarcodeFormatPDF417 (2D stacked barcode, used for IDs and transport)
  • PKBarcodeFormatCode128 (1D barcode for alphanumeric data)
NFC
nfc.message string path: nfc.message

The message transmitted when the pass is tapped on an NFC reader. Maximum 64 bytes.

Locations
location.latitude string path: locations.0.latitude

Latitude coordinate for the location-based notification trigger.

location.longitude string path: locations.0.longitude

Longitude coordinate for the location-based notification trigger.

location.message string path: locations.0.relevantText

Message displayed when the user is near the location.

Dates
relevant.date datetime path: relevantDate

Date and time when the pass becomes relevant. The pass appears on the lock screen near this time. Format: ISO 8601.

expiration.date datetime path: expirationDate

Date and time when the pass expires. After this time, the pass is marked as expired. Format: ISO 8601.

Advanced Event Ticket (Poster) iOS 18+ Premium

Enhanced event ticket with rich media, venue maps, and additional event information. Requires iOS 18+.

Premium

Advanced Poster Event Tickets are a Premium feature and require an active Premium or Enterprise plan.

Appearance
primary.logo file image (png) path: primaryLogo

Primary logo displayed prominently on the poster pass. Used for home team or main performer.

secondary.logo file image (png) path: secondaryLogo

Secondary logo for the poster pass. Used for away team or supporting performer.

artwork.image file image (png) path: artworkImage

Main artwork image for the event poster. Recommended size: 1170x1464px (3:4 aspect ratio).

venue.image file image (png) path: venueImage

Venue map or seating chart image displayed in the event guide view.

brand.logo file image (png) path: logo

Brand logo displayed at the top of the pass. Recommended size: 160x50px @1x.

brand.text string path: logoText

Brand name or organization text displayed with the logo.

icon.link file image (png) required path: icon

Pass icon for notifications and lock screen. Required size: 29x29px @1x.

label.color string path: labelColor

Color for field labels. Accepts hex color codes or rgb() values.

background.color string path: backgroundColor

Background color of the pass. Accepts hex color codes or rgb() values.

foreground.color string path: foregroundColor

Color for field values and text. Accepts hex color codes or rgb() values.

Event Details
event.type enum<string> path: semantics.eventType

The type of event for the poster ticket.

Available options:

  • PKEventTypeLivePerformance (concerts, live shows)
  • PKEventTypeSports (sporting events and matches)
  • PKEventTypeMovie (movie screenings and premieres)
  • PKEventTypeConference (professional conferences and summits)
  • PKEventTypeConvention (fan conventions and expos)
  • PKEventTypeWorkshop (hands-on workshops and tutorials)
  • PKEventTypeSocialGathering (parties and social events)
event.name string path: semantics.eventName

The name of the event displayed on the pass.

venue.region.name string path: semantics.venueRegionName

The region or city where the venue is located.

venue.name string path: semantics.venueName

The name of the venue hosting the event.

event.live.message string path: semantics.eventLiveMessage

Message displayed during the live event (e.g., "Event in progress").

admission.level string path: semantics.admissionLevel

The admission or ticket level (e.g., "VIP", "General Admission").

event.start.date datetime path: semantics.eventStartDate

Event start date and time. Format: ISO 8601.

event.end.date datetime path: semantics.eventEndDate

Event end date and time. Format: ISO 8601.

gates.open.date datetime path: semantics.venueGatesOpenDate

When venue gates open for entry. Format: ISO 8601.

Venue Location Info
venue.latitude string path: semantics.venueLocation.latitude

Latitude coordinate of the venue for maps and location-based notifications.

venue.longitude string path: semantics.venueLocation.longitude

Longitude coordinate of the venue for maps and location-based notifications.

location.message string path: locations.0.relevantText

Message shown when user is near the venue location.

Event Guide View
entrance.description string path: semantics.entranceDescription

Description of the venue entrance to use (e.g., "Use Gate B on West Side").

album.ids string path: semantics.albumIDs

Comma-separated Apple Music album IDs for event-related music.

appstore.id string path: auxiliaryStoreIdentifiers.0

App Store ID for the event's associated iOS app.

Action Panel
seat.section string path: semantics.seats.0.seatSection

Section designation for the seat (e.g., "Section 101").

seat.row string path: semantics.seats.0.seatRow

Row number or letter for the seat.

seat.number string path: semantics.seats.0.seatNumber

Specific seat number within the row.

seat.identifier string path: semantics.seats.0.seatIdentifier

Unique identifier for the seat in the venue system.

seat.description string path: semantics.seats.0.seatDescription

Additional description for the seating area.

seat.type string path: semantics.seats.0.seatType

Type of seating (e.g., "Floor", "Balcony", "Box").

attendee.name string path: semantics.attendeeName

Name of the ticket holder or attendee.

Additional Info Fields
additional.0.label string path: eventTicket.additionalInfoFields.0.label

Label for the additional info field displayed in the event guide.

additional.0.value string path: eventTicket.additionalInfoFields.0.value

Value text for the additional info field.

additional.0.dataDetectorType enum<string>

Type of data detector for the attributed value.

Available options:

  • link (tappable URL that opens in Safari)
  • phone (tappable phone number that initiates a call)
  • address (tappable address that opens in Maps)
  • calendar (tappable date that creates a calendar event)
additional.0.attributedValue string

The URL, phone number, address, or date for tappable content.

Actions
merchandise.url string path: merchandiseURL

URL for event merchandise store.

contact.phone string path: contactVenuePhoneNumber

Contact phone number for event support.

contact.email string path: contactVenueEmail

Contact email address for event support.

contact.url string path: contactVenueWebsite

URL for event contact or support page.

directions.url string path: directionsInformationURL

URL for venue directions (opens in Maps).

parking.url string path: parkingInformationURL

URL for parking information.

Performer Info
performer.names string path: semantics.performerNames

Comma-separated list of performer or artist names.

performer.artist_ids string path: semantics.artistIDs

Comma-separated Apple Music artist IDs for performer links.

performer.genre string path: semantics.genre

Music genre for the performer (e.g., "Rock", "Pop", "Hip-Hop").

performer.playlist_ids string path: semantics.playlistIDs

Comma-separated Apple Music playlist IDs for event-related playlists.

Sports Info
sports.home.abbrev string path: semantics.homeTeamAbbreviation

Abbreviation for the home team (e.g., "NYY", "LAL").

sports.away.abbrev string path: semantics.awayTeamAbbreviation

Abbreviation for the away team (e.g., "BOS", "GSW").

sports.home.name string path: semantics.homeTeamName

Full name of the home team (e.g., "New York Yankees").

sports.away.name string path: semantics.awayTeamName

Full name of the away team (e.g., "Boston Red Sox").

sports.home.location string path: semantics.homeTeamLocation

City or location of the home team (e.g., "New York").

sports.away.location string path: semantics.awayTeamLocation

City or location of the away team (e.g., "Boston").

sports.name string path: semantics.sportName

Name of the sport (e.g., "Baseball", "Basketball", "Football").

sports.league string path: semantics.leagueName

Full name of the league (e.g., "Major League Baseball").

sports.league.abbrev string path: semantics.leagueAbbreviation

Abbreviation for the league (e.g., "MLB", "NBA", "NFL").

Venue Info
venue.room string path: semantics.venueRoom

Specific room or hall within the venue.

Relevant Dates
relevant.0.start datetime

Start of the time range when the pass becomes relevant. Format: ISO 8601.

relevant.0.end datetime

End of the time range when the pass is relevant. Format: ISO 8601.

NFC
nfc.message string path: nfc.message

Message transmitted when the pass is tapped on an NFC reader. Maximum 64 bytes. If empty, the pass defaults to Barcode if set to anything other than none.

Barcode
barcode.alt string path: barcode.altText

Alternative text displayed below the barcode for manual entry.

barcode.data string path: barcode.message

The data encoded in the barcode. This value is scanned by barcode readers.

barcode.type enum<string> path: barcode.format

The barcode format to display on the pass.

Available options:

  • PKBarcodeFormatQR (2D square barcode, high data capacity)
  • PKBarcodeFormatPDF417 (2D stacked barcode, used for IDs and transport)
  • PKBarcodeFormatCode128 (1D barcode for alphanumeric data)
Access Control

For employee badges, visitor passes, and ID cards. Supports thumbnail image.

Appearance
brand.logo file image (png) path: logo

The logo image displayed at the top of the pass. Recommended size: 160x50px @1x.

brand.text string path: logoText

Text displayed next to or below the logo. Typically the organization name.

label.color string path: labelColor

Color used for field labels. Accepts hex color codes or rgb() values.

background.color string path: backgroundColor

Background color of the pass. Accepts hex color codes or rgb() values.

foreground.color string path: foregroundColor

Color used for field values and other text. Accepts hex color codes or rgb() values.

icon.link file image (png) path: icon

The pass icon shown in notifications and on the lock screen. Required size: 29x29px @1x.

thumbnail.image file image (png) Access Control only path: thumbnailImage

A thumbnail image displayed on the right side of the pass. Recommended size: 90x90px @1x (270x270px @3x) or 2:3 aspect ratio. Typically used for employee photos or ID portraits.

Header Fields
header.label string path: generic.headerFields.0.label

Label text displayed above the header field value.

header.value string path: generic.headerFields.0.value

Value displayed in the header field, shown at the top right of the pass.

Primary Fields
primary.label string path: generic.primaryFields.0.label

Label text for the primary field.

primary.value string path: generic.primaryFields.0.value

The main content displayed prominently on the pass. Typically the person's name.

Secondary Fields
secondary.0.label string path: generic.secondaryFields.0.label

Label for the first secondary field.

secondary.0.value string path: generic.secondaryFields.0.value

Value for the first secondary field.

secondary.1.label string path: generic.secondaryFields.1.label

Label for the second secondary field.

secondary.1.value string path: generic.secondaryFields.1.value

Value for the second secondary field.

Auxiliary Fields
auxiliary.0.label string path: generic.auxiliaryFields.0.label

Label for the first auxiliary field.

auxiliary.0.value string path: generic.auxiliaryFields.0.value

Value for the first auxiliary field.

auxiliary.1.label string path: generic.auxiliaryFields.1.label

Label for the second auxiliary field.

auxiliary.1.value string path: generic.auxiliaryFields.1.value

Value for the second auxiliary field.

auxiliary.2.label string path: generic.auxiliaryFields.2.label

Label for the third auxiliary field.

auxiliary.2.value string path: generic.auxiliaryFields.2.value

Value for the third auxiliary field.

Back Fields
back.label string path: generic.backFields.0.label

Label for the back field, shown when the pass is flipped.

back.value string path: generic.backFields.0.attributedValue

Value for the back field. Supports data detectors for links, phone numbers, addresses, and calendar events.

Barcode
barcode.alt string path: barcode.altText

Alternative text displayed below the barcode for manual entry.

barcode.data string path: barcode.message

The data encoded in the barcode. This value is scanned by barcode readers.

barcode.type enum<string> path: barcode.format

The barcode format to display on the pass.

Available options:

  • PKBarcodeFormatQR (2D square barcode, high data capacity)
  • PKBarcodeFormatPDF417 (2D stacked barcode, used for IDs and transport)
  • PKBarcodeFormatCode128 (1D barcode for alphanumeric data)
NFC
nfc.message string path: nfc.message

The message transmitted when the pass is tapped on an NFC reader. Maximum 64 bytes.

Locations
location.latitude string path: locations.0.latitude

Latitude coordinate for the location-based notification trigger.

location.longitude string path: locations.0.longitude

Longitude coordinate for the location-based notification trigger.

location.message string path: locations.0.relevantText

Message displayed when the user is near the location.

Dates
relevant.date datetime path: relevantDate

Date and time when the pass becomes relevant. The pass appears on the lock screen near this time. Format: ISO 8601.

expiration.date datetime path: expirationDate

Date and time when the pass expires. After this time, the pass is marked as expired. Format: ISO 8601.