API documentation

Base URL

https://walletissuer.com

All endpoints below are relative to this origin. API access and API keys are available on Pro and Pro Plus; Free and Starter plans, including their trials, cannot use the API. Create a key in the dashboard under API keys, then call from your backend or scripts. On Pro / Pro Plus, use Push notifications (POST /api/v1/passes/{serial}/notify) after changing fields so installed wallets refresh.

Authorization: Bearer wi_live_…

Dashboard session cookies are for the UI only. Automations and backends must use API keys. Missing or invalid keys return 401 with { "error": "…" }.

curl -X POST https://walletissuer.com/api/v1/passes \
  -H "Authorization: Bearer wi_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "logoText": "Acme Club",
    "title": "Membership",
    "header": "Member",
    "description": "Show at the door",
    "backgroundColor": "#0a0a0a",
    "foregroundColor": "#ffffff",
    "labelColor": "#c8c8c8",
    "fields": [
      { "key": "name", "label": "Name", "value": "Alex Rivera" },
      { "key": "tier", "label": "Tier", "value": "Gold" }
    ],
    "barcode": {
      "format": "QR_CODE",
      "message": "ACME-1001",
      "altText": "ACME-1001"
    }
  }'

201 response:

{
  "serial": "ps_…",
  "status": "active",
  "shareUrl": "https://walletissuer.com/p/ps_…",
  "googleSaveUrl": "https://pay.google.com/gp/v/save/…",
  "googleObjectId": "issuer.object",
  "applePass": null,
  "platforms": {
    "google": "issued",
    "apple": "pending"
  },
  "body": { /* normalized PassBody */ }
}

Creates count toward your monthly quota. If Google Wallet is not configured on the server, the request fails with 503.

curl https://walletissuer.com/api/v1/passes \
  -H "Authorization: Bearer wi_live_…"

List items are summaries (not full bodies). Use get-by-serial for the complete pass.

{
  "passes": [
    {
      "serial": "ps_…",
      "status": "active",
      "title": "Acme Club",
      "googleSaveUrl": "https://pay.google.com/gp/v/save/…",
      "googleObjectId": "issuer.object",
      "createdAt": 1728000000000,
      "updatedAt": 1728000000000,
      "shareUrl": "https://walletissuer.com/p/ps_…"
    }
  ]
}

curl https://walletissuer.com/api/v1/passes/{serial} \
  -H "Authorization: Bearer wi_live_…"

{
  "serial": "ps_…",
  "status": "active",
  "shareUrl": "https://walletissuer.com/p/ps_…",
  "googleSaveUrl": "https://pay.google.com/gp/v/save/…",
  "googleObjectId": "issuer.object",
  "applePass": null,
  "platforms": {
    "google": "issued",
    "apple": "pending"
  },
  "body": { /* full PassBody */ },
  "createdAt": 1728000000000,
  "updatedAt": 1728000000000
}

Unknown serials return 404.

Full-body replace. The request is run through the same normalizer as create. Omitted fields reset to defaults (for example logoText becomes "Pass"). Always send the complete body you want stored.

curl -X PUT https://walletissuer.com/api/v1/passes/ps_… \
  -H "Authorization: Bearer wi_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "logoText": "Acme Club",
    "title": "Membership",
    "header": "Member",
    "description": "Updated benefits",
    "backgroundColor": "#0a0a0a",
    "foregroundColor": "#ffffff",
    "labelColor": "#c8c8c8",
    "fields": [
      { "key": "name", "label": "Name", "value": "Alex Rivera" },
      { "key": "tier", "label": "Tier", "value": "Platinum" }
    ],
    "barcode": {
      "format": "QR_CODE",
      "message": "ACME-1001",
      "altText": "ACME-1001"
    }
  }'

Response shape matches get (full PassRecord). Content-changing updates count toward quota; identical bodies do not. Revoked passes cannot be updated (409).

To push the change to installed wallets with a lock-screen message, call POST …/notify — or enable auto-notify under Dashboard → Push notifications. See Push notifications.

How it works. Change the pass with PUT /api/v1/passes/{serial}, then send a push with POST /api/v1/passes/{serial}/notify. One call reaches both wallets:

• Apple Wallet — the pass is re-signed with your message as the changeMessage on its fields, then an APNs push wakes every registered device. Wallet downloads the new pass and shows the message on the lock screen.
• Google Wallet — the pass object is updated in place with your message as changeMessage on the header and text rows.

Lock-screen text on Apple. Apple Wallet only shows a field's changeMessage when that field's value changes. So every push also stamps a hidden back field (pushUpdate) with the current time. The message then appears even when no visible field changed.

Apple device registration. Apple devices register for pushes only when the installed pass carries the web service URL, which is added to passes created or updated while the workspace has Pro access. appleDevices in the response shows how many devices are registered for the serial.

Plan. Push notifications are included with Pro and Pro Plus. New Free workspaces receive a 30-day Starter trial without a card, then return to Free. Starter is also available as a paid monthly subscription. API endpoints require a Pro or Pro Plus subscription, so Free and Starter workspaces receive 403 with { "error": "…" } and this message:

API key access requires a Pro or Pro Plus subscription. Free and Starter plans, including trials, cannot use API endpoints.

Auto-notify on update. The pass body has no notification field. Instead, turn on auto-notify under Dashboard → Push notifications (dashboard only, not an API setting). With it on, every content-changing PUT /api/v1/passes/{serial} sends "Pass updated" automatically, and DELETE /api/v1/passes/{serial} sends "Pass revoked". Updates with an identical body do not notify. Auto-notify is best-effort: a failed push never fails the update or revoke. For custom text, leave it off and call notify yourself.

Request body (JSON, all fields optional):

curl -X POST https://walletissuer.com/api/v1/passes/{serial}/notify \
  -H "Authorization: Bearer wi_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "message": "You earned 50 points" }'

const res = await fetch("https://walletissuer.com/api/v1/passes/" + serial + "/notify", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.WALLETISSUER_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ message: "You earned 50 points" }),
});
const result = await res.json();
if (!res.ok) throw new Error(result.error);
// result.google: "updated" | "skipped" | "failed"
// result.apple:  "pushed"  | "skipped" | "failed"

200 response:

{
  "serial": "ps_…",
  "message": "You earned 50 points",
  "google": "updated",
  "apple": "pushed",
  "appleDevices": 1,
  "appleSent": 1,
  "appleMode": "token"
}

A 200 means the request was processed. Check google and apple for per-wallet results. Every send is recorded in the dashboard history under Push notifications. Notify calls do not count toward your monthly pass quota.

Errors

curl -X DELETE https://walletissuer.com/api/v1/passes/{serial} \
  -H "Authorization: Bearer wi_live_…"

Returns the pass with status: "revoked".

curl -X POST https://walletissuer.com/api/v1/assets \
  -H "Authorization: Bearer wi_live_…" \
  -F "file=@logo.png" \
  -F "kind=logo"

Multipart form: required file; optional kind — logo, icon, hero, strip, thumbnail, or other. PNG, JPEG, or WebP up to 1 MB.

201 response:

{
  "id": "ast_…",
  "orgId": "org_…",
  "kind": "logo",
  "r2Key": "orgs/…/ast_….png",
  "contentType": "image/png",
  "byteSize": 18432,
  "width": null,
  "height": null,
  "createdAt": 1728000000000,
  "url": "https://walletissuer.com/a/ast_…"
}

Put url into logoUrl, heroUrl, etc. on create or update. External HTTPS URLs also work if you host images yourself. Files are served publicly at /a/{assetId}. Free plan returns 403.

https://walletissuer.com/p/{serial}

Returned as shareUrl on create, list, get, update, and revoke. Updates keep the same URL. You can also manage passes from Pass manager in the dashboard without calling the API.

• Free — 1,000 / month; no API access, custom images (image URL fields stripped) and no push notifications. New workspaces start with a 30-day Starter trial (Starter features and quota), then return to Free.
• Starter — 10,000 / month; custom images and live loyalty updates. Available as a paid monthly subscription; new Free accounts can try Starter for 30 days without a card. API tools require Pro or Pro Plus.
• Pro — 100,000 / month; custom images via /api/v1/assets or external HTTPS URLs; Push notifications API.
• Pro Plus — 1,000,000 / month soft limit; custom images, push notifications, and team features.

Generate keys on Pro or Pro Plus under Dashboard → API keys after signing up.