> ## 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.

# Add points

> Adds or subtracts points on a points card pass, counted from its current balance.

TapAce adds `add` to the pass's current balance, so two requests at the same time both count. The balance never goes past the template's limits: below the minimum, or above the goal (or the maximum when there's no goal). Adding to a balance already at its limit leaves it there. To set an exact balance instead, send `points` to [Update a pass](https://tapace.lk/docs/api-reference/passes/update.md). See [Points cards](https://tapace.lk/docs/guides/points-cards.md).

**id** `string` *required*

The pass ID. The pass must be an active points card.

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

A unique value for this change, so a retry never adds the points twice. See [Idempotency](https://tapace.lk/docs/idempotency.md).

**add** `number` *required*

How many points to add, with up to 2 decimal places, such as `50` or `12.5`. A negative number subtracts points. Between `-9999999.99` and `9999999.99`, and not `0`.

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

`silent` updates the pass quietly. `notify` also shows the template's points message on the holder's lock screen, or its goal message when this takes the balance to the goal. See [When the goal is reached](https://tapace.lk/docs/guides/points-cards.md#when-the-goal-is-reached).

### Response

**pass** `object`

The updated [pass](https://tapace.lk/docs/api-reference/passes/get.md). `points.balance` is the new balance.

**update** `object | null`

A record of the change, as in [Update a pass](https://tapace.lk/docs/api-reference/passes/update.md), with `changes.points` holding the `from` and `to` balances, the `change` you asked for and the template's `goal`. `change` stays what you sent even when a limit stopped the balance short. It's `null` when the balance didn't move, for example when adding to a balance already at the goal.

### Errors

| Status | When |
| - | - |
| `400` | `add` is 0, has more than 2 decimal places or is out of range, the pass isn't a points card, or the pass is voided. |
| `404` | The pass doesn't exist. |
| `409` | The pass kept changing while the points were being added. Retry the request. |

```bash cURL theme={null}
curl https://api.tapace.lk/v1/passes/pass_7hGk2LmQ9xVt4RnB8cYe/points \
  -H "Authorization: Bearer $TAPACE_API_KEY" \
  -H "Idempotency-Key: 9d4b2e7a-1c8f-4a3e-b6d0-7e5f2a9c1b38" \
  -H "Content-Type: application/json" \
  -d '{ "add": 50, "notificationMode": "notify" }'
```

```json 201 theme={null}
{
  "pass": {
    "object": "pass",
    "id": "pass_7hGk2LmQ9xVt4RnB8cYe",
    "status": "active",
    "fieldValues": { "memberNumber": "TC-00284" },
    "points": { "balance": 400, "min": 0, "max": null, "goal": 1000 },
    "updatedAt": "2026-10-31T10:30:00.000Z"
  },
  "update": {
    "object": "pass_update",
    "id": "pupd_Rk3Wv8Mt2Lq6Nz9Px4Cd",
    "passId": "pass_7hGk2LmQ9xVt4RnB8cYe",
    "notificationMode": "notify",
    "walletChanged": true,
    "changes": {
      "fields": [],
      "points": { "from": 350, "to": 400, "change": 50, "goal": 1000 }
    },
    "delivery": {
      "apple": { "status": "pending", "devices": 1, "error": null },
      "google": { "status": "pending", "message": "pending", "error": null }
    },
    "createdAt": "2026-10-31T10:30:00.000Z"
  }
}
```

```json 400 theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "message": "Only points card passes have points."
  },
  "requestId": "req_8f3a2c1d9e7b6a54"
}
```


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