API Documentation

What each field does

Edit any field and see the pass update live

Editing pass loading...

View all passes

Logo Text

Text next to the logo (top-left)

Organization Name (optional)

Notification title on pass updates. Defaults to your account name.

Header Fields (top-right)

No header fields

The poster layout shows the first header field only.

Primary Fields (main content)

No primary fields

Without a background image Apple shows only the first primary field on the pass face; Google shows the first as the title and lists the rest in the pass details.

The poster layout shows up to four primary fields on the pass face; Google shows the first as the title and lists the rest in the pass details.

Secondary Fields (below primary)

No secondary fields

The poster layout keeps secondary fields off the pass face on iOS 27; older devices and Google still show them.

Footer Fields (poster layout) Pro

Pro feature

Included in your trial until .

Available on Pro and Business.

Up to two short lines along the bottom of the poster layout.

Apple shows the value only; the label is saved but not drawn.

Without a background image Apple keeps them off the pass face; Google still lists them in the pass details.

Back Fields (back of pass)

No back fields

Lock-Screen Locations (/10) Pro

Pro feature

Included in your trial until .

Available on Pro and Business.

Click the pin to fill a row with where you are, for testing. The real pass needs the actual place.

Wallet shows the pass on the lock screen within ~100m of a coordinate.

Pro feature — upgrade to add up to 10 lock-screen location triggers per pass.

Featured Actions (/) Pro

Pro feature

Included in your trial until .

Available on Pro and Business.

Up to two buttons under the pass. Apple sets the icon and wording; Google Wallet shows them as links.

Pro feature. Upgrade to add up to two buttons under the pass.

Barcode None (no barcode) QR PDF417 Aztec Code128

Barcode Value

Line breaks are kept, so a multi-line value such as a vCard scans as one. Up to 1024 characters.

Override Text Under Barcode

By default Google prints the value under the code and Apple prints nothing.

Expiration No expiration 30 days 90 days 180 days 365 days

Color Preset Dark Blue Green Red Purple Orange

Custom Color Pro

Pro feature

Included in your trial until .

Available on Pro and Business.

Overrides color preset

EXPIRES

Google Wallet fills the screen with the pass: your background image becomes a full-width band under the fields, and featured actions become tappable rows.

Overview

Authentication

Authorization: Bearer ww_live_<your_key>

Returns your current monthly usage statistics. Requires authentication.

Headers

Response

{
  "count": 150,
  "limit": 1000,
  "remaining": 850,
  "resetDate": "2026-03-01",
  "plan": "free"
}

plan is one of free, trial, pro, business, or enterprise (the Scale plan). A new account starts on trial, which carries every feature at the free volume for 7 days and then reverts to free unless you subscribe. A live trial also returns trialExpiresAt. limit is the volume your plan includes and remaining counts down against it. On business and enterprise the included limit is soft: requests keep working past it and we reach out to discuss your volume.

curl https://api.walletwallet.dev/api/auth/usage \
  -H "Authorization: Bearer ww_live_<your_key>"

Issues a pass to both wallets in one call. Returns JSON { serialNumber, googleSaveUrl, applePass, shareUrl }, where applePass is the base64-encoded signed .pkpass, googleSaveUrl is the Save to Google Wallet link, and shareUrl is a hosted install page for the same pass. This is the canonical endpoint. Requires authentication.

Headers

Request Body

Response

{
  "serialNumber": "8f4c3a2e-...",
  "googleSaveUrl": "https://pay.google.com/gp/v/save/<jwt>",
  "applePass": "UEsDBBQAAAAI...(base64 .pkpass)",
  "shareUrl": "https://pass.walletwallet.dev/p/8f4c3a2e-...",
  "credentials": "platform"
}

curl -X POST https://api.walletwallet.dev/api/passes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ww_live_<your_key>" \
  -d '{
    "barcodeValue": "MEMBER-12345",
    "barcodeFormat": "QR",
    "logoText": "Membership Card"
  }'

curl -X POST https://api.walletwallet.dev/api/passes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ww_live_<your_key>" \
  -d '{
    "barcodeValue": "LOYALTY-98765",
    "barcodeFormat": "QR",
    "logoText": "Bayroast Coffee",
    "description": "Loyalty card for Bayroast Coffee",
    "primaryFields": [{"label": "CARD", "value": "Coffee Rewards"}],
    "secondaryFields": [{"label": "TIER", "value": "Gold Status"}],
    "headerFields": [{"label": "BALANCE", "value": "$25.00"}],
    "colorPreset": "green",
    "expirationDays": 365
  }'

curl -X POST https://api.walletwallet.dev/api/passes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ww_live_<your_key>" \
  -d '{
    "barcodeValue": "VIP-001",
    "barcodeFormat": "QR",
    "logoText": "VIP Access",
    "primaryFields": [{"label": "PASS", "value": "VIP Access"}],
    "color": "#8B4513",
    "logoURL": "https://example.com/logo.png"
  }'

Updates a previously-issued pass. Devices that have it installed receive an Apple Push Notification within seconds; Wallet refreshes the pass in place with a lock-screen banner. Requires authentication and ownership of the serial.

Headers

Request Body

Same shape as POST /api/passes: send the full pass spec. The server replaces the stored body, recomputes a content hash, and fans out push notifications to registered devices.

• The URL path's <serial> identifies the pass — do not include serialNumber in the body.
• authenticationToken is server-owned and immutable once issued; including it in the body returns 400.
• To surface a custom lock-screen banner on update, add changeMessage on the field whose value is changing (e.g. "You earned %@ points"). iOS substitutes %@ with the new value.
• An identical body returns { unchanged: true } with no push and no quota impact — safe to retry.

Response

{
  "serialNumber": "8f4c3a2e-...",
  "lastUpdated": 1778538208273,
  "notifiedDevices": 3,
  "unchanged": false
}

{
  "serialNumber": "8f4c3a2e-...",
  "lastUpdated": 1778538208273,
  "notifiedDevices": 0,
  "unchanged": true
}

curl -X PUT https://api.walletwallet.dev/api/passes/<serial> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ww_live_<your_key>" \
  -d '{
    "barcodeValue": "LOYALTY-98765",
    "barcodeFormat": "QR",
    "logoText": "Bayroast Coffee",
    "primaryFields": [{"label": "CARD", "value": "Coffee Rewards"}],
    "secondaryFields": [
      {
        "label": "POINTS",
        "value": "250",
        "changeMessage": "You now have %@ points"
      }
    ],
    "colorPreset": "green"
  }'

Revokes a pass you issued: it is invalidated on every device it is installed on, on both wallets. Requires authentication and ownership of the serial. The legacy alias DELETE /api/pkpass/<serial> works the same way.

Headers

No request body is needed; any body is ignored. The serial in the URL path identifies the pass.

Response

{
  "serialNumber": "8f4c3a2e-...",
  "deleted": true,
  "googleRevoked": true,
  "notifiedDevices": 3,
  "lastUpdated": 1778538208273
}

{
  "serialNumber": "8f4c3a2e-...",
  "deleted": true,
  "alreadyDeleted": true,
  "notifiedDevices": 0
}

curl -X DELETE https://api.walletwallet.dev/api/passes/<serial> \
  -H "Authorization: Bearer ww_live_<your_key>"

Share a pass

Send a notification

To push a custom lock-screen notification on demand, ship a backFields "notification anchor". Put the message text in value, and set changeMessage to literally "%@". The wallet substitutes %@ with the new value at render time, so the banner reads whatever you wrote.

Two mechanics make the seed-then-bump pattern necessary. The notification fires only when a field's value actually changes between pass versions. And your changeMessage text is honored only when it contains %@; without it, the banner falls back to a generic "Pass Changed" string.

1. Seed the anchor on pass creation

The anchor must exist on the pass before any update can target it. If it does not, the first send is silently suppressed by rule 1.

curl -X POST https://api.walletwallet.dev/api/passes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ww_live_<your_key>" \
  -d '{
    "barcodeValue": "MEMBER-12345",
    "barcodeFormat": "QR",
    "logoText": "Loyalty Card",
    "backFields": [
      { "label": "Notifications", "value": " ", "changeMessage": "%@" }
    ]
  }'

2. Send a message

Bump the anchor's value to the message text. Keep changeMessage as "%@".

curl -X PUT https://api.walletwallet.dev/api/passes/<serial> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ww_live_<your_key>" \
  -d '{
    "barcodeValue": "MEMBER-12345",
    "barcodeFormat": "QR",
    "logoText": "Loyalty Card",
    "backFields": [
      { "label": "Notifications", "value": "Free coffee on us!", "changeMessage": "%@" }
    ]
  }'

Practical notes

• The anchor lives in backFields so it does not crowd the pass face. Customers only see "Notifications: <last message>" if they tap ⓘ to flip the pass.
• Keep the backFields array order stable between POST and every PUT. Fields are identified by position; reordering the array re-keys the anchor and the banner stops firing.
• If you skip the POST seed, the first PUT introduces the anchor as a brand-new field, which is treated as "no value change" and silently suppresses the banner. Subsequent sends work because the anchor now exists, so only the first is silent.
• Sending the same message twice in a row is a no-op. The value did not change, so no banner fires. Vary the text if you need a repeat.

Your own certificates

Endpoints

All endpoints take your API key or a dashboard session and answer 403 on Free. Secret material is stored encrypted and never echoed back.

Rules

• Deleting a set, removing its Apple certificate, uploading a certificate for a different pass type, or changing or removing its Google issuer answers 409 with the number of live passes it would strand. Revoke them first, or add ?force=true. After a forced change those passes stop serving with 410, which makes Apple Wallet unregister them, and their Google objects stop updating.
• An Apple pass type id belongs to one set across all accounts. A Google issuer belongs to one account but may appear in several of its sets. Claiming one that is taken answers 409, naming the set when it is yours.
• An Apple certificate with no APNs key signs passes correctly but can never push an update, so installed passes go stale with no error. Add the key.
• A pass keeps its set for life. After a downgrade to Free it still serves, updates, and pushes; only new creates that name a set answer 403.

Barcode Formats

Color Presets

Available on all plans. Use the colorPreset field.

Rate Limits

{
  "error": "Rate limit exceeded",
  "resetDate": "2026-03-01",
  "message": "Monthly limit reached. Resets on 2026-03-01"
}

Errors

All error responses return JSON with an error field:

{
  "error": "Error message describing the issue"
}

HTTP Status Codes

Common Validation Errors

Code Examples

const response = await fetch('https://api.walletwallet.dev/api/passes', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ww_live_<your_key>'
  },
  body: JSON.stringify({
    barcodeValue: 'TICKET-789',
    barcodeFormat: 'QR',
    logoText: 'Event Ticket',
    primaryFields: [{ label: 'EVENT', value: 'Concert' }],
    secondaryFields: [{ label: 'Seat', value: 'A-23' }]
  })
});

if (!response.ok) {
  const error = await response.json();
  throw new Error(error.error);
}

// One JSON response covers both wallets
const { serialNumber, googleSaveUrl, applePass } = await response.json();
// googleSaveUrl -> "Add to Google Wallet" link. applePass -> base64 .pkpass.

// Browser: trigger the Apple Wallet download
const bytes = Uint8Array.from(atob(applePass), c => c.charCodeAt(0));
const url = URL.createObjectURL(new Blob([bytes], { type: 'application/vnd.apple.pkpass' }));
const a = document.createElement('a');
a.href = url;
a.download = 'ticket.pkpass';
a.click();

// Node.js: save to file
// const fs = require('fs');
// fs.writeFileSync('ticket.pkpass', Buffer.from(applePass, 'base64'));

import requests, base64

response = requests.post(
    'https://api.walletwallet.dev/api/passes',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer ww_live_<your_key>'
    },
    json={
        'barcodeValue': 'ORDER-456',
        'barcodeFormat': 'Code128',
        'logoText': 'Order Pickup',
        'primaryFields': [{'label': 'ORDER', 'value': 'Pickup'}],
        'secondaryFields': [{'label': 'Order #', 'value': '456'}]
    }
)

response.raise_for_status()
data = response.json()
# data['serialNumber'], data['googleSaveUrl'] (Add to Google Wallet link)

with open('order.pkpass', 'wb') as f:
    f.write(base64.b64decode(data['applePass']))

require 'net/http'
require 'json'
require 'uri'
require 'base64'

uri = URI('https://api.walletwallet.dev/api/passes')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['Authorization'] = 'Bearer ww_live_<your_key>'
request.body = {
  barcodeValue: 'MEMBER-001',
  barcodeFormat: 'QR',
  logoText: 'Gym Membership',
  primaryFields: [{ label: 'MEMBER', value: 'Premium' }]
}.to_json

response = http.request(request)
data = JSON.parse(response.body)
# data['serialNumber'], data['googleSaveUrl']
File.binwrite('membership.pkpass', Base64.decode64(data['applePass']))

$ch = curl_init('https://api.walletwallet.dev/api/passes');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer ww_live_<your_key>'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'barcodeValue' => 'COUPON-50OFF',
        'barcodeFormat' => 'QR',
        'logoText' => 'Discount Coupon',
        'primaryFields' => [['label' => 'COUPON', 'value' => '50% Off']]
    ])
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $data = json_decode($response, true);
    // $data['serialNumber'], $data['googleSaveUrl']
    file_put_contents('coupon.pkpass', base64_decode($data['applePass']));
}

package main

import (
    "bytes"
    "encoding/base64"
    "encoding/json"
    "net/http"
    "os"
)

func main() {
    body, _ := json.Marshal(map[string]interface{}{
        "barcodeValue":  "PASS-999",
        "barcodeFormat": "QR",
        "logoText":      "Access Pass",
    })

    req, _ := http.NewRequest("POST", "https://api.walletwallet.dev/api/passes", bytes.NewBuffer(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer ww_live_<your_key>")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var data map[string]string
    json.NewDecoder(resp.Body).Decode(&data)
    // data["serialNumber"], data["googleSaveUrl"]

    pkpass, _ := base64.StdEncoding.DecodeString(data["applePass"])
    os.WriteFile("access.pkpass", pkpass, 0644)
}