PassKit Web Service Reference
A Representational State Transfer (REST)–style web service protocol is used to communicate with your server about changes to passes, and to fetch the latest version of a pass when it has changed. The endpoints always begin with the web service URL, as specified in the pass, followed by the protocol version number. For example, a request for the latest version of the pass of type com.apple.pass.example
and serial number ABC123
might look like the following:

All of the endpoints, including the logging endpoint, are required.
For all endpoints, specify the application/json
MIME type for responses that contain JSON data, and the application/vnd.apple.pkpass
for responses that contain a Wallet pass.
If a request fails—for example, due to a network connectivity issue—PassKit tries again several times after waiting a period of time. Each time it tries again, it waits longer. If the request continues to fail, it eventually gives up.
Registering a Device to Receive Push Notifications for a Pass
POST request to webServiceURL/
version/devices/
deviceLibraryIdentifier/registrations/
passTypeIdentifier/
serialNumber
Parameters
- webServiceURL
The URL to your web service, as specified in the pass.
- version
The protocol version—currently, v1.
- deviceLibraryIdentifier
A unique identifier that is used to identify and authenticate this device in future requests.
- passTypeIdentifier
The pass’s type, as specified in the pass.
- serialNumber
The pass’s serial number, as specified in the pass.
Header
The Authorization header is supplied; its value is the word ApplePass
, followed by a space, followed by the pass’s authorization token as specified in the pass.
Payload
The POST payload is a JSON dictionary containing a single key and value:
- pushToken
The push token that the server can use to send push notifications to this device.
Response
If the serial number is already registered for this device, returns HTTP status 200.
If registration succeeds, returns HTTP status 201.
If the request is not authorized, returns HTTP status 401.
Otherwise, returns the appropriate standard HTTP status.
Discussion
Any time the pass is updated, your server sends a push notification with an empty JSON dictionary as the payload to the device using the given push notification token. This process continues until the device is explicitly unregistered (as described in Unregistering a Device).
Getting the Serial Numbers for Passes Associated with a Device
GET request to webServiceURL/
version/devices/
deviceLibraryIdentifier/registrations/
passTypeIdentifier?passesUpdatedSince=
tag
Parameters
- webServiceURL
The URL to your web service, as specified in the pass.
- version
The protocol version—currently, v1.
- deviceLibraryIdentifier
A unique identifier that is used to identify and authenticate the device.
- passTypeIdentifier
The pass’s type, as specified in the pass.
- tag
A tag from a previous request. (optional)
If the
passesUpdatedSince
parameter is present, returns only the passes that have been updated since the time indicated bytag
. Otherwise, returns all passes.
Response
If there are matching passes, returns HTTP status 200 with a JSON dictionary with the following keys and values:
lastUpdated
(string)The current modification tag.
serialNumbers
(array of strings)The serial numbers of the matching passes.
If there are no matching passes, returns HTTP status 204.
Otherwise, returns the appropriate standard HTTP status.
Discussion
The modification tag is used to give a name to a point in time. It is typically convenient to use a timestamp, but the server can use another approach. The tag is treated as an opaque value by the system.
Getting the Latest Version of a Pass
GET request to webServiceURL/
version/passes/
passTypeIdentifier/
serialNumber
Parameters
- webServiceURL
The URL to your web service, as specified in the pass.
- version
The protocol version—currently, v1.
- passTypeIdentifier
The pass’s type, as specified in the pass.
- serialNumber
The unique pass identifier, as specified in the pass.
Header
The Authorization header is supplied; its value is the word ApplePass
, followed by a space, followed by the pass’s authorization token as specified in the pass.
Response
If request is authorized, returns HTTP status 200 with a payload of the pass data.
If the request is not authorized, returns HTTP status 401.
Otherwise, returns the appropriate standard HTTP status.
Discussion
Support standard HTTP caching on this endpoint: Check for the If-Modified-Since
header, and return HTTP status code 304 if the pass has not changed.
Unregistering a Device
DELETE request to webServiceURL/
version/devices/
deviceLibraryIdentifier/registrations/
passTypeIdentifier/serialNumber
Parameters
- webServiceURL
The URL to your web service, as specified in the pass.
- version
The protocol version—currently, v1.
- deviceLibraryIdentifier
A unique identifier that is used to identify and authenticate the device.
- passTypeIdentifier
The pass’s type, as specified in the pass.
- serialNumber
The unique pass identifier, as specified in the pass.
Header
The Authorization header is supplied; its value is the word ApplePass
, followed by a space, followed by the pass’s authorization token as specified in the pass.
Response
If disassociation succeeds, returns HTTP status 200.
If the request is not authorized, returns HTTP status 401.
Otherwise, returns the appropriate standard HTTP status.
Discussion
The server disassociates the specified device from the pass, and no longer sends push notifications to this device when the pass changes.
Logging Errors
POST request to webServiceURL/
version/log
Parameters
- webServiceURL
The URL to your web service, as specified in the pass.
- version
The protocol version—currently, v1.
Payload
The POST payload is a JSON dictionary, containing a single key and value:
logs
(string)An array of log messages as strings.
Response
Returns HTTP status 200.
Discussion
This endpoint is intended to help you debug your web service implementation. Log messages contain a description of the error in a human-readable format.
Copyright © 2015 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2015-09-16