> ## 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 a pass

> Changes a pass's field values, links, external ID or metadata. Wallet changes are pushed to every wallet that has it.

Send only what changes. See [Update passes](https://tapace.lk/docs/guides/update-passes.md) for how notifications and delivery work.

**id** `string` *required*

The pass ID.

**Idempotency-Key** `string` *required*

A unique value for this update.

**fieldValues** `object`

New values keyed by field key. Each value is a string, a number, or `null` to clear an optional field. Fields you leave out keep their values.

**featuredActions** `object`

New Featured Action links, keyed by action key. Each link must start with `https://`, or `tel:` for a call action. `null` or an empty string removes the pass's own link so the template's link shows again. A link the template requires for every pass can't be removed, and an action whose link is the same on every pass can't be set. Actions you leave out keep their links. Only with `notificationMode: "silent"`.

**relevance** `object`

New Lock Screen lists: `locations` and `dates`, in the same format as in [Issue a pass](https://tapace.lk/docs/api-reference/passes/issue.md). A list you send replaces the pass's own, `null` returns it to the template's list, and a list you leave out stays as it is. Only with `notificationMode: "silent"`.

**stamps** `integer`

Stamp cards only: the new stamp count, a whole number from 0 to the card's total. To add or remove stamps without knowing the count, use [Add stamps](https://tapace.lk/docs/api-reference/passes/add-stamps.md).

**points** `number`

Points cards only: the new balance, with up to 2 decimal places. A value outside the template's limits is moved to the nearest one. To add or subtract points without knowing the balance, use [Add points](https://tapace.lk/docs/api-reference/passes/add-points.md).

**notificationMode** `string` (default: silent)

`silent` updates the pass quietly. `notify` also shows a notification on the holder's lock screen. Only applies when field values, stamps or points change.

**externalId** `string | null`

A new external ID, up to 255 characters. `null` or an empty string clears it.

**metadata** `object`

Keys to set or remove. It's merged into the pass's metadata: a string sets that key, `null` or an empty string removes it, and keys you leave out stay as they are. The result can have at most 50 keys.

`externalId` and `metadata` never reach the wallet, so changing them sends nothing to the holder, and you can still change them after the pass is voided.

### Response

**pass** `object`

The updated [pass](https://tapace.lk/docs/api-reference/passes/get.md).

**update** `object | null`

A record of the change, with its delivery to each wallet. It's `null` when nothing visible in the wallet changed, for example when you only changed `metadata`. Check its progress later with [Get a pass update](https://tapace.lk/docs/api-reference/passes/get-update.md).

**properties**

**id** `string`

Unique ID, starting with `pupd_`.

**notificationMode** `string`

`silent` or `notify`.

**changes** `object`

What changed. `fields` lists each field with its `key`, `label`, `from` and `to` values. On a stamp card, `stamps` has the `from` and `to` counts and the card's `total`. On a points card, `points` has the `from` and `to` balances, the `change` asked for and the template's `goal`. `featuredActions` and `relevance` appear when those changed. See [the pass update object](https://tapace.lk/docs/api-reference/passes/get-update.md).

**delivery** `object`

Progress per wallet: `apple.status` and `google.status`. See [delivery status](https://tapace.lk/docs/guides/update-passes.md#delivery-status).

### Errors

| Status | When |
| - | - |
| `400` | A key isn't a per-pass field, a required field would be cleared, a Featured Action is unknown, can't be set per pass, has an invalid link or is required and would be removed, `relevance` is invalid, Featured Action links or `relevance` changed with `notificationMode: "notify"`, `metadata` breaks its limits, `stamps` is outside 0 to the card's total or the pass isn't a stamp card, `points` has more than 2 decimal places or the pass isn't a points card, nothing changed, or field values were sent for a voided pass. |
| `404` | The pass doesn't exist. |
| `409` | The pass changed while this update was being saved. Retry the request. |

```bash cURL theme={null}
curl -X PATCH https://api.tapace.lk/v1/passes/pass_7hGk2LmQ9xVt4RnB8cYe \
  -H "Authorization: Bearer $TAPACE_API_KEY" \
  -H "Idempotency-Key: 0b9e4c1a-7d2f-4e8b-a6c3-5f1d9e2b7a40" \
  -H "Content-Type: application/json" \
  -d '{
    "fieldValues": { "points": 150 },
    "notificationMode": "notify",
    "metadata": { "plan": "platinum" }
  }'
```

```json 200 theme={null}
{
  "pass": {
    "object": "pass",
    "id": "pass_7hGk2LmQ9xVt4RnB8cYe",
    "status": "active",
    "externalId": "cus_8812",
    "metadata": { "plan": "platinum" },
    "fieldValues": { "memberName": "Nimal Perera", "points": 150 },
    "updatedAt": "2026-10-13T10:30:00.000Z"
  },
  "update": {
    "object": "pass_update",
    "id": "pupd_Lm4Xq8Vt2Nr7Kz3Pw9Bc",
    "passId": "pass_7hGk2LmQ9xVt4RnB8cYe",
    "notificationMode": "notify",
    "walletChanged": true,
    "changes": {
      "fields": [
        { "key": "points", "label": "Points", "from": "120", "to": "150" }
      ]
    },
    "delivery": {
      "apple": { "status": "pending", "devices": 1, "error": null },
      "google": { "status": "pending", "message": "pending", "error": null }
    },
    "createdAt": "2026-10-13T10:30:00.000Z"
  }
}
```


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