Update passes

Updating a pass changes it on every phone that has it. The holder keeps the same pass and doesn’t have to add it again.

Change field values

Send only the fields that change to PATCH /v1/passes/{id}. Fields you leave out keep their values.

curl -X PATCH https://api.tapace.lk/v1/passes/pass_7hGk2LmQ9xVt4RnB8cYe \
  -H "Authorization: Bearer $TAPACE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "fieldValues": { "points": 150, "tier": "Gold" } }'

Use the field keys from the template, the same ones you send when issuing.
Send null or an empty string to clear an optional field. A required field can only be cleared if the template gives it a default value.
Only per-pass fields can be updated. Shared fields change when you edit the template.

Notify the holder

By default an update is silent: the pass changes without an alert. Set notificationMode to notify to show a notification on the holder’s lock screen:

{
  "fieldValues": { "points": 150 },
  "notificationMode": "notify"
}

Google Wallet allows 3 notifications per pass in 24 hours. Beyond that, the pass still updates but no alert is shown.

Delivery status

The response contains the updated pass and an update object. update.delivery reports how the change reached each wallet:

Status	Meaning
`pending`	The update is being sent.
`delivered`	The delivery operation succeeded. For Apple, the update signal was accepted; this does not confirm the device fetched or displayed the new pass.
`not_installed`	No wallet has saved the pass yet. It will show the new values when it’s added.
`skipped`	The pass isn’t issued for this wallet.
`failed`	The update couldn’t be sent. `error` explains why.
`superseded`	A newer update replaced this one before it was sent.

A silent update changes the pass without an alert banner. Confirm the visible value on the installed pass separately from API delivery status. For Apple Wallet, check Automatic Updates if the display remains stale. An update usually starts as pending. To see where it ended up, fetch it again with Get a pass update, using update.id:

curl https://api.tapace.lk/v1/passes/pass_7hGk2LmQ9xVt4RnB8cYe/updates/pupd_Lm4Xq8Vt2Nr7Kz3Pw9Bc \
  -H "Authorization: Bearer $TAPACE_API_KEY"

List pass updates returns the pass’s whole history, including changes made in the dashboard.

Your own IDs and metadata

Store your own reference on a pass with externalId, and any extra details with metadata. Set them when you issue the pass or change them later with the same PATCH request. Neither appears on the pass, so changing them sends nothing to the holder:

{
  "externalId": "cus_8812",
  "metadata": { "plan": "platinum", "trial": null }
}

metadata is merged: plan is set, trial is removed, and other keys stay as they are. To find a customer’s passes, call GET /v1/passes?externalId=cus_8812.

Send a message

To tell holders something without changing a value, send a notification. It can go out now or at a time up to a day ahead:

Send to a pass for one holder. On Apple Wallet it appears in the pass’s Message for you field.
Send to a template for every holder. On Apple Wallet it appears in the pass’s Announcements field.

curl https://api.tapace.lk/v1/passes/pass_7hGk2LmQ9xVt4RnB8cYe/notifications \
  -H "Authorization: Bearer $TAPACE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "appleText": "Your table is ready.",
    "googleTitle": "Table ready",
    "googleBody": "Your table is ready. Please come to the front desk."
  }'

Apple Wallet only alerts when the text changes, so a message identical to the one already on the pass is rejected. Scheduled messages can be changed or cancelled until they’re sent.

Roll out a new design

When you update a template with a new definition, passes already issued keep their old design. To move them to the new one, deploy the template:

curl https://api.tapace.lk/v1/templates/tmpl_Q4vN8xT2mLr7KpZs3Wd1/deployments \
  -H "Authorization: Bearer $TAPACE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "notificationMode": "silent" }'

TapAce works out which passes change, then updates them in every wallet. Get the deployment to follow its progress, and list its results to see each pass.

Void a pass

To end a pass, such as a cancelled membership or a refunded ticket, void it. Voiding is permanent: the pass is marked as voided in the holder’s wallet and its field values can’t be changed again. You can still change its externalId and metadata.

Delete a pass

To remove a pass and its history, such as when a customer deletes their account, delete it. Deleting voids the pass if it’s active, and the API and dashboard stop returning it at once. To remove a template and all of its passes, delete the template.

Use the Node.js SDK

Use tapace.passes.update() for fields or an exact loyalty balance, passes.addStamps() and passes.addPoints() for balance adjustments, and passes.retrieveUpdate() for delivery progress. Use notification methods for messages and deployment methods to roll out a saved design. See SDK resource methods for examples. Give each intended mutation its own saved operation ID and stable key. Do not repeat a credit just because a phone has not refreshed.

Getting started

Basics

Guides

Node.js SDK

API keys

Passes

Loyalty cards

Notifications

Templates

Wallet signing

Deployments

Assets

Change field values

Notify the holder

Delivery status

Your own IDs and metadata

Send a message

Roll out a new design

Void a pass

Delete a pass

Use the Node.js SDK

​Change field values

​Notify the holder

​Delivery status

​Your own IDs and metadata

​Send a message

​Roll out a new design

​Void a pass

​Delete a pass

​Use the Node.js SDK

Change field values

Notify the holder

Delivery status

Your own IDs and metadata

Send a message

Roll out a new design

Void a pass

Delete a pass

Use the Node.js SDK