API reference · Passes

Update a pass

PUT/v1/passes/{serial}1 operation, only when something changesSafe to retry with Idempotency-Key

Replaces its fields. Installed passes refresh on holders' phones, and a field with a changeMessage shows a notification when its value changes.

Path

serialstringrequired

The pass's serialNumber.

Body

All of the pass's fields, as they should now be: a field you leave out is removed. Or, for a pass with placeholders, only data and holder: they're merged over its values ("" clears one) and its design is filled again.

issuerstring

Optional: the pass's own set. A pass keeps its set for life, so naming another is refused.

dataobject

Values for the placeholders in its text, such as { "points": 120 }.

holderobject

The holder's name and email. Kept with the pass, so you can find one person's passes.

unlinkTemplateboolean

For a pass made from a template: true to replace its design, which stops the template updating it.

Answer

200Updated

notifiedDevices is how many Apple devices are being sent it. platforms: Apple queued, no_devices or no_push_key (its issuer has no push key); Google queued or not_saved.

200Nothing changed

The same fields again: no new version, nothing sent, and no operation used. Safe to send on every change in your system.

Errors

Every error has the same shape: see Errors.

Status	Code	When
400	`validation_error`	A field is missing, too long or unknown.
400	`placeholder_missing`	A required placeholder has no value.
404	`not_found`	No pass with that serial number in this workspace.
409	`pass_revoked`	It's revoked, so it can't change.
409	`template_linked`	It was made from a template: send `data` and `holder`, or `"unlinkTemplate": true` to replace its design.
409	`external_id_conflict`	Another pass has that `externalId`.
409	`idempotency_conflict`	The Idempotency-Key was already used for a different request.
422	`issuer_immutable`	`issuer` names another set: a pass keeps its set for life.
429	`usage_limit_exceeded`	This month's operations on your plan are used up.
429	`workspace_limit_reached`	This workspace's monthly limit, set by its organization, is used up.
429	`platform_usage_limit`	A test pass, and the 1,000 test operations a month are used up.

Request

curl -X PUT "https://api.walletpassapi.com/v1/passes/9f904677-e06d-4b0f-8404-878ff1066f88" \
  -H "Authorization: Bearer $WALLET_API_KEY" \
  -H "Idempotency-Key: points-1042-135" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationName": "Acme Coffee",
    "logoText": "Acme",
    "style": "loyalty",
    "primaryFields": [
      {
        "key": "points",
        "label": "Points",
        "value": "135",
        "changeMessage": "You now have %@ points"
      }
    ],
    "barcodeValue": "MEMBER-1042",
    "barcodeFormat": "QR",
    "externalId": "crm-1042"
  }'

const res = await fetch("https://api.walletpassapi.com/v1/passes/9f904677-e06d-4b0f-8404-878ff1066f88", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.WALLET_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "points-1042-135",
  },
  body: JSON.stringify({
    "organizationName": "Acme Coffee",
    "logoText": "Acme",
    "style": "loyalty",
    "primaryFields": [
      {
        "key": "points",
        "label": "Points",
        "value": "135",
        "changeMessage": "You now have %@ points"
      }
    ],
    "barcodeValue": "MEMBER-1042",
    "barcodeFormat": "QR",
    "externalId": "crm-1042"
  }),
});
const data = await res.json();

import os

import requests

res = requests.put(
    "https://api.walletpassapi.com/v1/passes/9f904677-e06d-4b0f-8404-878ff1066f88",
    headers={"Authorization": f"Bearer {os.environ['WALLET_API_KEY']}", "Idempotency-Key": "points-1042-135"},
    json={
        "organizationName": "Acme Coffee",
        "logoText": "Acme",
        "style": "loyalty",
        "primaryFields": [
            {
                "key": "points",
                "label": "Points",
                "value": "135",
                "changeMessage": "You now have %@ points",
            },
        ],
        "barcodeValue": "MEMBER-1042",
        "barcodeFormat": "QR",
        "externalId": "crm-1042",
    },
)
data = res.json()

<?php

$ch = curl_init("https://api.walletpassapi.com/v1/passes/9f904677-e06d-4b0f-8404-878ff1066f88");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("WALLET_API_KEY"),
        "Content-Type: application/json",
        "Idempotency-Key: points-1042-135",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "organizationName" => "Acme Coffee",
        "logoText" => "Acme",
        "style" => "loyalty",
        "primaryFields" => [
            [
                "key" => "points",
                "label" => "Points",
                "value" => "135",
                "changeMessage" => "You now have %@ points",
            ],
        ],
        "barcodeValue" => "MEMBER-1042",
        "barcodeFormat" => "QR",
        "externalId" => "crm-1042",
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

200 Updated

{
  "serialNumber": "9f904677-e06d-4b0f-8404-878ff1066f88",
  "version": 4,
  "lastUpdated": "2026-10-08T19:31:12.000Z",
  "notifiedDevices": 1,
  "unchanged": false,
  "notified": true,
  "platforms": {
    "apple": "queued",
    "google": "queued"
  }
}

200 Nothing changed

{
  "serialNumber": "9f904677-e06d-4b0f-8404-878ff1066f88",
  "version": 4,
  "lastUpdated": "2026-10-08T19:31:12.000Z",
  "notifiedDevices": 0,
  "unchanged": true,
  "platforms": {
    "apple": "unchanged",
    "google": "unchanged"
  }
}