Updating passes

Passform supports two levels of update: pass-level changes that affect a single issued pass, and template-level changes that propagate to every pass issued from that template.

Updating a pass

Use the same endpoint to create and update a pass — it behaves as an upsert. Calling it with an existing pass ID updates that pass in place.

POST /v1/pass/{templateId}/{passId}

An upsert replaces the whole pass. Send every field you want the pass to keep, not just the ones that changed. Fields you omit are reset: fields, backFields, locations, primaryValue, and metadata are removed, expiry and validFrom are cleared, voided returns to false, and code falls back to the pass ID.

If you don’t hold the current pass data, fetch it first with GET /v1/pass/{templateId}/{passId}, change what you need, and send the result back. Pass fields:

Field	Description
`fields`	The fields displayed on the front of the pass. Each `key` must exist on the template.
`backFields`	Fields shown on the back of the pass. Each `key` must exist on the template.
`primaryValue`	The primary value displayed on membership and generic passes
`expiry`	Pass expiry date — omit or set to `null` for no expiry
`validFrom`	Date from which the pass becomes valid
`voided`	Set to `true` to void the pass
`code`	The barcode/QR code value. Defaults to the pass ID. Must fit the length and character limits of the template’s `barcodeFormat` - see barcode types.
`locations`	Up to 10 locations that surface this pass on the lock screen, added to the template’s locations - see notifications
`metadata`	Free-form data for your own use - see metadata

Example — update a membership points balance: Read the pass so you have its current values:

curl https://api.passform.io/v1/pass/my-membership-template/member-123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Then send the complete pass back with the new primaryValue. Every other value is repeated unchanged, including the ones you aren’t updating:

curl -X POST https://api.passform.io/v1/pass/my-membership-template/member-123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "primaryValue": "1,850",
    "code": "MEM-000123",
    "validFrom": null,
    "expiry": "2027-06-30T23:59:59Z",
    "voided": false,
    "fields": [
      { "key": "tier", "label": "Tier", "value": "Gold" }
    ],
    "backFields": [
      { "key": "joined", "label": "Member since", "value": "March 2024" }
    ],
    "locations": [
      {
        "name": "Acme Queen St",
        "address": "12 Queen St, Auckland",
        "latitude": -36.848461,
        "longitude": 174.763336
      }
    ],
    "metadata": {
      "customerId": "cust_abc123"
    }
  }'

You only need to send the fields your pass actually uses. A pass that has never had backFields, locations, or metadata set has nothing to lose by omitting them. Example — void a pass: Voiding works the same way: send the complete pass with voided set to true, so the voided pass keeps its content.

curl -X POST https://api.passform.io/v1/pass/my-membership-template/member-123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voided": true,
    "primaryValue": "1,850",
    "code": "MEM-000123",
    "validFrom": null,
    "expiry": "2027-06-30T23:59:59Z",
    "fields": [
      { "key": "tier", "label": "Tier", "value": "Gold" }
    ],
    "backFields": [
      { "key": "joined", "label": "Member since", "value": "March 2024" }
    ],
    "locations": [
      {
        "name": "Acme Queen St",
        "address": "12 Queen St, Auckland",
        "latitude": -36.848461,
        "longitude": 174.763336
      }
    ],
    "metadata": {
      "customerId": "cust_abc123"
    }
  }'

How updates reach the wallet

After a pass is updated, Passform automatically notifies both wallets:

Apple Wallet — a silent push notification is sent to each device that has the pass installed. Apple Wallet then fetches the latest version of the pass in the background. The user sees the updated pass the next time they open it.
Google Wallet — the pass object is updated directly via the Google Wallet API. Changes are reflected immediately.

No additional API calls are needed to trigger this — it happens automatically on every upsert. By default the wallet updates are queued and the API responds as soon as the pass is saved. Set waitForWalletUpdates to true in the request body to have the API wait until both wallets have been notified before it responds. To show the user a lock-screen message alongside a change, see push messages.

Moving a pass to another template

Move a pass to a different template of the same type — for example from a “Silver” membership template to a “Gold” one. The pass keeps its ID and all of its field values, and the copies already installed in Apple Wallet and Google Wallet are updated in place rather than replaced.

POST /v1/pass/{templateId}/{passId}/move

curl -X POST https://api.passform.io/v1/pass/silver-members/member-123/move \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: move-member-123-to-gold" \
  -d '{
    "toTemplateId": "gold-members"
  }'

After the move the pass lives at /v1/pass/gold-members/member-123. To change field values as well, follow up with an upsert at the new template.

A move removes the pass from its original template, so retrying a request that already succeeded returns a 404. To make retries safe, send the optional Idempotency-Key header with a unique value per move — a retry with the same key replays the original response instead.

The API returns 400 if the two templates have different types, and 409 if a pass with the same ID already exists on the destination template.

Updating a template

Updating a template changes the appearance and shared content of every pass issued from it — colors, images, logo, title, and default field values.

POST /v1/templates/{templateId}

The request must always include the template’s required fields, even when you’re only changing one of them. Example — update a template’s banner image:

curl -X POST https://api.passform.io/v1/templates/my-offer-template \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "offer",
    "title": "Summer Sale",
    "issuerName": "Acme Co",
    "foregroundColor": "#FFFFFF",
    "backgroundColor": "#1a1a2e",
    "icon": "https://cdn.example.com/icon.png",
    "logo": "https://cdn.example.com/logo.png",
    "banner": "https://cdn.example.com/new-banner.png"
  }'

How template updates propagate

When a template is updated, Passform:

Updates the Google Wallet class — all Google Wallet passes reflect the new design immediately
Rebuilds the Apple Wallet pass template with the new values
Sends a push notification to every device that has a pass from this template, prompting Apple Wallet to fetch the updated version

This means a single template update can refresh the look and feel of thousands of passes at once — useful for seasonal rebrands, updated artwork, or correcting a typo in shared content.

Archiving a template

Archive a template you no longer need with POST /v1/templates/{templateId}/archive. This voids every pass issued from the template and blocks new passes from being created on it.

Pass data vs template data

Template updates affect shared design and default content only. Per-pass data — fields, primaryValue, expiry, voided — is stored on the individual pass and is not affected by template updates.

Changed on	Affects
Template	Colors, images, logo, title, issuer name, default fields, barcode format, locations
Pass	`fields`, `backFields`, `primaryValue`, `expiry`, `validFrom`, `voided`, `code`, `locations`

Metadata

Metadata is a free-form object you can attach to a pass for your own tracking purposes. It is not displayed in the wallet, and is limited to 5,000 characters when serialized to JSON.

PATCH /v1/pass/{templateId}/{passId}/metadata

Updating metadata through this endpoint does not trigger a wallet push — it is a silent server-side change only, and it leaves the rest of the pass untouched.

curl -X PATCH https://api.passform.io/v1/pass/my-template/pass-123/metadata \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "customerId": "cust_abc123",
      "source": "pos"
    }
  }'

Metadata is also part of the pass upsert body. Because an upsert replaces the whole pass, upserting without metadata removes any metadata already stored on the pass.

Getting started

Guides

Integrations

Updating a pass

How updates reach the wallet

Moving a pass to another template

Updating a template

How template updates propagate

Archiving a template

Pass data vs template data

Metadata

​Updating a pass

​How updates reach the wallet

​Moving a pass to another template

​Updating a template

​How template updates propagate

​Archiving a template

​Pass data vs template data

​Metadata

Updating a pass

How updates reach the wallet

Moving a pass to another template

Updating a template

How template updates propagate

Archiving a template

Pass data vs template data

Metadata