> ## Documentation Index
> Fetch the complete documentation index at: https://tapace.lk/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Update passes

> Change a saved pass and notify the holder.

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}`](https://tapace.lk/docs/api-reference/passes/update). Fields you leave out keep their values.

```bash theme={null}
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:

```json theme={null}
{
  "fieldValues": { "points": 150 },
  "notificationMode": "notify"
}
```

> [!NOTE]
>
> 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](https://tapace.lk/docs/api-reference/passes/get-update.md), using `update.id`:

```bash theme={null}
curl https://api.tapace.lk/v1/passes/pass_7hGk2LmQ9xVt4RnB8cYe/updates/pupd_Lm4Xq8Vt2Nr7Kz3Pw9Bc \
  -H "Authorization: Bearer $TAPACE_API_KEY"
```

[List pass updates](https://tapace.lk/docs/api-reference/passes/list-updates.md) 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:

```json theme={null}
{
  "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`](https://tapace.lk/docs/api-reference/passes/list).

## 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](https://tapace.lk/docs/api-reference/notifications/send-to-pass.md) for one holder. On Apple Wallet it appears in the pass's **Message for you** field.
* [Send to a template](https://tapace.lk/docs/api-reference/notifications/send-to-template.md) for every holder. On Apple Wallet it appears in the pass's **Announcements** field.

```bash theme={null}
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](https://tapace.lk/docs/api-reference/notifications/update.md) or [cancelled](https://tapace.lk/docs/api-reference/notifications/cancel.md) until they're sent.

## Roll out a new design

When you [update a template](https://tapace.lk/docs/api-reference/templates/update.md) with a new `definition`, passes already issued keep their old design. To move them to the new one, [deploy the template](https://tapace.lk/docs/api-reference/deployments/create.md):

```bash theme={null}
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](https://tapace.lk/docs/api-reference/deployments/get.md) to follow its progress, and [list its results](https://tapace.lk/docs/api-reference/deployments/results.md) to see each pass.

## Void a pass

To end a pass, such as a cancelled membership or a refunded ticket, [void it](https://tapace.lk/docs/api-reference/passes/void.md). 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](https://tapace.lk/docs/api-reference/passes/delete.md). 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](https://tapace.lk/docs/api-reference/templates/delete.md).

## 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](https://tapace.lk/docs/sdk/node/resources.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.