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

# Stamp cards

> Issue loyalty stamp cards and add stamps as customers visit.

A stamp card shows a row of stamps that fill in as the holder collects them, such as ten coffees toward a free one. TapAce draws the stamps for each pass and updates them in the holder's wallet whenever the count changes.

## Set up the card

Create a template from the **Stamp Card** starter in the dashboard, then change it in the designer. A stamp card template has the type `stamp_card`. In the designer you choose:

* How many stamps the card has, up to 10, and how many sit in a row.
* The stamp: a built-in icon or your own image, and how empty slots look.
* The colour or image behind the stamps.
* The text of the notification sent when stamps change, and optionally a different one for when the card fills.
* For Google Wallet, the fields shown as **Member ID** (a required per-pass field) and **Member name**.

Apple Wallet shows the stamps as a strip across the pass. Google Wallet shows them along the bottom of the card, with the count as the card's balance, such as `7 / 10`. A field can also show the count on the pass itself.

## Issue a card

Issue it like any pass with [`POST /v1/passes`](https://tapace.lk/docs/api-reference/passes/issue). It starts with no stamps, or send `stamps` to start with some:

```bash theme={null}
curl https://api.tapace.lk/v1/passes \
  -H "Authorization: Bearer $TAPACE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tmpl_Q4vN8xT2mLr7KpZs3Wd1",
    "fieldValues": { "memberNumber": "BB-00284", "memberName": "Nimal Perera" },
    "stamps": 1
  }'
```

The pass's `stamps` holds the count and the card's total: `{ "count": 1, "total": 10 }`.

## Add a stamp

When the holder earns a stamp, call [Add stamps](https://tapace.lk/docs/api-reference/passes/add-stamps.md):

```bash theme={null}
curl https://api.tapace.lk/v1/passes/pass_7hGk2LmQ9xVt4RnB8cYe/stamps \
  -H "Authorization: Bearer $TAPACE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "add": 1 }'
```

* TapAce counts from the pass's current stamps, so two stamps added at the same time both count.
* A negative `add` removes stamps, for example to undo a mistake.
* The count stays between 0 and the card's total. A full card stays full until you lower the count; TapAce doesn't track rewards, so reset the card when the holder redeems one.

To set an exact count, such as `0` after a reward is redeemed, send `stamps` to [Update a pass](https://tapace.lk/docs/api-reference/passes/update.md):

```json theme={null}
{ "stamps": 0 }
```

## Notify the holder

Stamp changes are silent unless you send `"notificationMode": "notify"`. The notification uses the text set on the template, with the count filled in, such as "7 / 10 stamps, closer to a free coffee". On Apple Wallet it appears on the lock screen; on a card without a field showing the count, it replaces the pass's **Message for you**.

### When the card fills

The template can also set a card-full notification, such as "Congratulations! Your card is full. Show it to collect your free coffee." It's sent instead of the usual text when a notifying change takes the count to the card's total, whether through [Add stamps](https://tapace.lk/docs/api-reference/passes/add-stamps.md) or by setting `stamps`.

* On Apple Wallet it replaces the pass's **Message for you**, and the holder gets just this one alert.
* On Google Wallet it has its own title and message.
* A silent change that fills the card stays silent.
* If the template has no card-full text, the usual one is sent.

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

## Change the design

If you change the number of stamps and [deploy the template](https://tapace.lk/docs/api-reference/deployments/create.md), passes with more stamps than the new total are lowered to it. The change shows in each pass's [update history](https://tapace.lk/docs/api-reference/passes/list-updates.md).

## Use the Node.js SDK

Call `tapace.passes.addStamps(passId, { add: 2, notificationMode: "silent" }, options)` to credit two stamps. The response contains the updated pass and an optional wallet update record. Silent updates have no alert banner.

Supply a stable idempotency key derived from the saved sale or award ID, and reuse the same body for retries. A new purchase needs a new operation ID. See the [SDK loyalty example](https://tapace.lk/docs/sdk/node/resources.md#credit-loyalty-balances).


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