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

> Adds or removes stamps on a stamp card pass, counted from its current stamps.

TapAce adds `add` to the pass's current count, so two requests at the same time both count. The count never goes below 0 or above the card's total: adding to a full card leaves it full. To set an exact count instead, send `stamps` to [Update a pass](https://tapace.lk/docs/api-reference/passes/update.md). See [Stamp cards](https://tapace.lk/docs/guides/stamp-cards.md).

**id** `string` *required*

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

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

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

**add** `integer` *required*

How many stamps to add, from `1` to `10`. A negative number, down to `-10`, removes stamps.

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

`silent` updates the pass quietly. `notify` also shows the template's stamp message on the holder's lock screen, or its card-full message when this fills the card. See [When the card fills](https://tapace.lk/docs/guides/stamp-cards.md#when-the-card-fills).

### Response

**pass** `object`

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

**update** `object | null`

A record of the change, as in [Update a pass](https://tapace.lk/docs/api-reference/passes/update.md), with `changes.stamps` holding the `from` and `to` counts and the card's `total`. It's `null` when the count didn't move, for example when adding to a full card.

### Errors

| Status | When |
| - | - |
| `400` | `add` is 0 or outside -10 to 10, the pass isn't a stamp card, or the pass is voided. |
| `404` | The pass doesn't exist. |
| `409` | The pass kept changing while the stamps were being added. Retry the request. |

```bash cURL theme={null}
curl https://api.tapace.lk/v1/passes/pass_7hGk2LmQ9xVt4RnB8cYe/stamps \
  -H "Authorization: Bearer $TAPACE_API_KEY" \
  -H "Idempotency-Key: 3c8e1f2a-9b7d-4e6c-a1f0-5d2b8c7e9a14" \
  -H "Content-Type: application/json" \
  -d '{ "add": 1, "notificationMode": "notify" }'
```

```json 201 theme={null}
{
  "pass": {
    "object": "pass",
    "id": "pass_7hGk2LmQ9xVt4RnB8cYe",
    "status": "active",
    "fieldValues": { "memberNumber": "BB-00284" },
    "stamps": { "count": 7, "total": 10 },
    "updatedAt": "2026-10-23T10:30:00.000Z"
  },
  "update": {
    "object": "pass_update",
    "id": "pupd_Qm7Xv2Lt9Nr4Kz8Pw3Bc",
    "passId": "pass_7hGk2LmQ9xVt4RnB8cYe",
    "notificationMode": "notify",
    "walletChanged": true,
    "changes": {
      "fields": [],
      "stamps": { "from": 6, "to": 7, "total": 10 }
    },
    "delivery": {
      "apple": { "status": "pending", "devices": 1, "error": null },
      "google": { "status": "pending", "message": "pending", "error": null }
    },
    "createdAt": "2026-10-23T10:30:00.000Z"
  }
}
```

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


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