Wallet Pass API

Create Apple Wallet passes and serve them to devices.

Passes

POST /passes

Create a new pass and store it.

Request body
{
  "organizationName": "Acme Inc",
  "style":            "storeCard",
  "description":      "Loyalty card",
  "logoText":         "Acme",
  "barcodeValue":     "1234567890",

  "headerFields":    [{ "key": "balance", "label": "Balance", "value": "$10" }],
  "primaryFields":   [{ "key": "name",    "label": "Member",  "value": "Jane" }],
  "secondaryFields": [],
  "auxiliaryFields": [],
  "backFields":      [],

  "foregroundColor": "rgb(255,255,255)",
  "backgroundColor": "rgb(30,30,30)",
  "labelColor":      "rgb(200,200,200)",

  "iconUrl":       "https://cdn.example.com/icon.png",
  "iconUrl2x":     "https://cdn.example.com/icon@2x.png",
  "iconUrl3x":     "https://cdn.example.com/icon@3x.png",
  "logoUrl":       "https://cdn.example.com/logo.png",
  "logoUrl2x":     "...",
  "logoUrl3x":     "...",
  "thumbnailUrl":  "...",
  "stripUrl":      "...",
  "backgroundUrl": "...",
  "footerUrl":     "..."
}

style defaults to generic; valid values: generic, storeCard, coupon, eventTicket, boardingPass. All *Url fields are optional and fetched at download time — icon URLs default to a plain dark square if omitted. Each image slot has Url, Url2x, and Url3x variants.

Response
{
  "serialNumber": "...",
  "downloadUrl": "https://.../passes/..."
}
GET /passes/:serialNumber

Download the generated .pkpass file.

Response

Binary application/vnd.apple.pkpass.

GET /passes/:serialNumber/payload

Return the stored input payload plus server timestamps. Use this to hydrate a UI editor with the pass's current state.

Response
{
  // ...every field that was last POST'd or PATCH'd...
  "serialNumber": "...",
  "createdAt":    "2026-05-21T...",
  "updatedAt":    "2026-05-21T..."
}
PATCH /passes/:serialNumber

Update a pass and push to every device that's registered for it. Merge-patch: keys you send replace; keys you omit are kept.

Request body
{
  "primaryFields": [{ "key": "balance", "label": "Balance", "value": "$25" }]
}
Response
{
  "ok": true,
  "updatedAt": "2026-05-21T..."
}

Apple Wallet Web Service

Called by iOS devices. Requires header Authorization: ApplePass <authenticationToken> where noted.

POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber

Register a device for push updates. Requires auth.

Request body
{ "pushToken": "..." }
Response

201 Created

GET /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier

List serial numbers updated since a given tag.

Query
Response
{ "lastUpdated": "2026-05-21T...", "serialNumbers": ["..."] }

Returns 204 when there are no changes.

GET /v1/passes/:passTypeIdentifier/:serialNumber

Fetch the latest pass file for a device. Requires auth.

Response

Binary application/vnd.apple.pkpass.

DELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber

Unregister a device. Requires auth.

Response

200 OK