> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/guides-design/design/stamp-card.md).

# Stamp card

Configure a stamp card template for Apple Wallet and Google Wallet: stamp goal, behavior when full, one image per stamp count and a reward benefit.

A stamp card is the digital version of the paper loyalty card stamped at each visit: "buy nine coffees, the tenth is on us". The pass shows how many stamps have been collected, the picture on the card changes with every stamp, and when the goal is reached The Wallet Crew can grant a reward automatically.

A stamp card is its own type of pass template in The Wallet Crew. It looks and behaves like a loyalty card in Apple Wallet and Google Wallet. Because the count lives on the pass itself, a stamp card works without any external loyalty system.

<details>

<summary><strong>Real-world examples</strong></summary>

* **Coffee shop:** ten stamps for a free drink of the customer's choice. The card shows a cup filling up, and the reward appears on the pass when the tenth stamp lands.
* **Car wash:** five washes, the sixth is free. The card stays full until the free wash is taken, then starts a new round.
* **Bakery or pizzeria:** one stamp per purchase, with a seasonal design applied through a theme.
* **Barber, pet grooming, juice bar or gym:** one stamp per visit or class, with a reward benefit used at the counter in Pass Scanner.
* **Event series:** one stamp per attended match or concert, with a collector reward at the end of the season.

</details>

## How a stamp card works

Each stamp card pass carries a stamp board: the count, the goal and the list of every stamp added or corrected. Adding a stamp pushes the update to the holder's wallet.

```mermaid
flowchart LR
    S["Stamp added<br/>(API, Pass Scanner)"] --> C["Count + 1<br/>image of the new count"]
    C --> G{"Goal reached?"}
    G -- No --> W["Pass updated<br/>in the wallet"]
    G -- Yes --> R["Reward benefit granted<br/>(optional)"]
    R --> B{"When the goal is reached"}
    B -- "Stay full, clear on the next stamp" --> F1["Full board shown,<br/>next stamp starts a new round"]
    B -- "Clear straight away" --> F2["Board empties at once"]
    B -- "Stay full" --> F3["Card takes no more stamps"]
```

### On Apple Wallet

On Apple Wallet, a stamp card uses the store card layout, like a loyalty card. The **strip** image behind the primary field is replaced by the image of the current stamp count, so the holder sees the stamps fill up.

When **Use new poster layout** is enabled on the Apple tab, iPhones running iOS 27 or later display the card with the poster layout, and the **poster artwork** of the current count is used instead of the strip. Older iPhones keep the classic layout with the strip, which is why the strip images stay required. See [Pass style and layout](https://docs.thewalletcrew.io/configure/advanced-configuration/wallet/template-configuration/apple-tab.md#pass-style-and-layout) for the poster layout and the other Apple Wallet fields, and the [loyalty card guide](https://docs.thewalletcrew.io/guides-design/design/loyalty-card-template-configuration.md#poster-layout-on-ios-27) for poster image tips.

### On Google Wallet

On Google Wallet, a stamp card is a loyalty pass. The **hero** image is replaced by the image of the current stamp count. The count is not written automatically into Google's points field: to display it as text, reference the stamp variables in a field (see [Show the count in pass fields](#show-the-count-in-pass-fields)).

## Create a stamp card template

A stamp card template is created like any other pass template, then completed with its stamp settings and images. To grant a reward when the card is full, create the [benefit template](https://docs.thewalletcrew.io/guides-animation/engage-and-animate/benefit-templates.md) of the reward first.

{% hint style="info" %}
**Benefit templates are in beta.** Switch on **Beta features** in the profile menu, at the top right of the admin console, to see **Engagement → Benefit templates**.
{% endhint %}

{% stepper %}
{% step %}

#### Create the template

Open **Wallet → Templates**, click **Add new**, and choose **Stamp card**. Ready-made stamp card starters are available for a bakery, a coffee shop, a pizzeria, a car wash, pet grooming, a juice bar, a barber and a gym. They come with a stamp count, a goal behavior and artwork for each stamp count, and are a good base to adapt.
{% endstep %}

{% step %}

#### Set the goal

On the **General** tab, fill the **Stamps** card: the number of stamps to reach the goal, what happens when it is reached, and the optional reward benefit template.
{% endstep %}

{% step %}

#### Add one image per stamp count

On the **Apple** tab, open **Images → Stamp images** and add a strip image for each count, plus a poster artwork for each count when the poster layout is enabled. On the **Google** tab, add a hero image for each count.
{% endstep %}

{% step %}

#### Check the preview and save

Use the preview on the right to check the card at different counts, then click **Save**. The template is validated on save: every required image must be present.
{% endstep %}
{% endstepper %}

To turn an existing loyalty card into a stamp card, create a new stamp card template and move the passes to it, for example with an [automation](https://docs.thewalletcrew.io/guides-animation/engage-and-animate/automatisation.md) using **Change the pass template**.

### Stamp settings

The **Stamps** card on the **General** tab defines how many stamps reach the goal, and what the pass does when it gets there.

<figure><img src="https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2Fgit-blob-6697b60d80e0a4646faa02214e9c8f36a2b57427%2Fstamp-card-stamps-settings-single-frame.png?alt=media" alt="The Stamps card sets the goal, the behavior when the card is full, and the reward benefit template."><figcaption><p>The Stamps card sets the goal, the behavior when the card is full, and the reward benefit template.</p></figcaption></figure>

| Setting                      | Description                                                                                                                                                                                                                                            |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Stamps to reach the goal** | Required. Between 1 and 100.                                                                                                                                                                                                                           |
| **When the goal is reached** | What the card does once full. See the options below.                                                                                                                                                                                                   |
| **Reward benefit template**  | Optional. A [benefit template](https://docs.thewalletcrew.io/guides-animation/engage-and-animate/benefit-templates.md) granted once the goal is reached, for example "Free drink of your choice". Choose **No reward** to manage the reward elsewhere. |

| When the goal is reached                         | What the holder sees                                                                                        | Best for                                                                                         |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Stay full, clear on the next stamp** (default) | The full board stays visible. The next stamp clears the board and counts as the first stamp of a new round. | Most programs: the holder enjoys a full card until the next visit.                               |
| **Clear straight away**                          | The board empties the moment the goal is reached, so a full board is never shown.                           | Programs where the reward is the only signal the holder needs.                                   |
| **Stay full**                                    | The card refuses further stamps once full.                                                                  | One-off collections, such as a season of matches, where a new card is issued for the next round. |

The reward benefit is granted once per round. When the goal is reached again while the previous reward is still on the pass, the existing reward is refreshed rather than duplicated, so a holder carries one live reward at a time.

### Stamp images

Stamp images make progress visible: there is one image for each count the card can display, from **Empty** (0 stamps) to the goal. A card with a goal of 10 therefore needs 11 images per image slot. With **Clear straight away**, the full card is never displayed, so the image of the goal count is not needed.

<figure><img src="https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2Fgit-blob-1bba3d98c9cd89b766f3e1f660984430d5b6da22%2Fstamp-card-apple-stamp-images-single-frame.png?alt=media" alt="Stamp images lists one row per stamp count, from Empty to the goal, each with its own image."><figcaption><p>Stamp images lists one row per stamp count, from Empty to the goal, each with its own image.</p></figcaption></figure>

| Slot             | Where                             | Size           | Required                                                    |
| ---------------- | --------------------------------- | -------------- | ----------------------------------------------------------- |
| **Apple strip**  | Apple tab → Images → Stamp images | 1200 × 462 px  | For every count.                                            |
| **Apple poster** | Apple tab → Images → Stamp images | 1236 × 1680 px | For every count, when **Use new poster layout** is enabled. |
| **Google hero**  | Google tab → Stamp images         | 1032 × 336 px  | For every count.                                            |

Wallet apps crop images that do not match these proportions, so keep the stamps away from the edges. Changing the goal adds or removes rows in the editor; filled rows keep their images.

{% hint style="info" %}
A simple way to produce the images is to design the empty card once, then export one version per count with one more stamp filled each time. Name the files by count, for example `stamp-0.png` to `stamp-10.png`, to upload them in order.
{% endhint %}

### Show the count in pass fields

The stamp board is available to every field of the template through Liquid, which is useful for a text such as "7 / 10 stamps" or "3 more for a free drink".

| Variable                 | Value                                        |
| ------------------------ | -------------------------------------------- |
| `{{ stamps.count }}`     | Stamps collected. 0 on a card never stamped. |
| `{{ stamps.target }}`    | Stamps needed to reach the goal.             |
| `{{ stamps.remaining }}` | Stamps still needed, never below 0.          |

For example, a secondary field with the value `{{ stamps.remaining }} more for a free drink` keeps the holder informed on both wallets. See [Liquid templating](https://docs.thewalletcrew.io/developers-guides/integration-guides/wallet/templating-engine.md) for the syntax.

## Add stamps

Stamps are added at the counter with Pass Scanner, or by a system such as a POS or an e-commerce platform through the API. Every movement is recorded with its date, its value, who applied it and an optional remark.

### From the admin console

The pass page shows the count of a stamp card next to its type, for example **7 / 10 stamps**, and the preview draws the board as the holder sees it.

<figure><img src="https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2Fgit-blob-05e2821965b56b0457928c4ca8a754c6a88449c2%2Fstamp-card-pass-overview-stamp-count.png?alt=media" alt="The pass overview shows the stamp count next to the pass type, and the preview shows the board with five stamps out of eight."><figcaption><p>The pass overview shows the stamp count, and the preview shows the board with five stamps out of eight.</p></figcaption></figure>

The **Stamps** tab of the pass holds the **Stamp board**: the count against the goal, the state of the card (**Collecting** or goal reached), what happens after the goal, and the reward. Below it, a grid lists every movement with its **Date**, the **Stamps** added or removed, who applied it (**Applied by**) and the **Remarks**.

<figure><img src="https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2Fgit-blob-8320fd2e2203bf70ba9befd0bb5f9afb45d57a62%2Fstamp-card-pass-stamps-tab.png?alt=media" alt="The Stamps tab shows the stamp board with 5 of 8 stamps and every movement, with who applied it and the remarks."><figcaption><p>The stamp board shows 5 of 8 stamps and every movement, with who applied it and the remarks.</p></figcaption></figure>

**Apply stamps** records a movement by hand, for example for a purchase made without the card or to correct a mistake.

{% stepper %}
{% step %}

#### Open the dialog

On the pass page, open the **Stamps** tab and click **Apply stamps**. The dialog shows the current count and the count after the movement, for example "Currently 5 of 10 → 7".
{% endstep %}

{% step %}

#### Set the stamps to apply

Set **Stamps to apply**: a positive number to stamp the card, a negative number to correct it. The dialog shows the **Room left** before the goal and never lets the count go above the goal or below zero.
{% endstep %}

{% step %}

#### Add a remark and confirm

Add **Remarks (optional)**, such as the receipt number, then click **Apply stamps**. The pass is updated in the holder's wallet.
{% endstep %}
{% endstepper %}

<figure><img src="https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2Fgit-blob-e2e8ec424515737a0688f2c909a0f0785652ab26%2Fstamp-card-apply-stamps-dialog.png?alt=media" alt="Applying two stamps with the receipt number as a remark takes the card from 5 to 7 stamps."><figcaption><p>Applying two stamps with the receipt number as a remark takes the card from 5 to 7 stamps.</p></figcaption></figure>

### With Pass Scanner

Staff can stamp a card when the [Pass Scanner profile](https://docs.thewalletcrew.io/guides-scan/scan/pass-scanner/pass-scanner-profiles.md) running on the device has **Staff can add stamps** switched on. Each tap of **Add a stamp** applies one stamp. See [Stamp cards in Pass Scanner](https://docs.thewalletcrew.io/guides-scan/scan/pass-scanner.md#stamp-cards).

### With the API

Integrations add stamps with the stamp card endpoint of the pass.

| Operation             | Endpoint                                      |
| --------------------- | --------------------------------------------- |
| Read the stamp board  | `GET /api/{tenantId}/passes/{passId}/stamps`  |
| Add or correct stamps | `POST /api/{tenantId}/passes/{passId}/stamps` |

The request body carries:

| Field      | Description                                                                                                                                                                 |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`    | Required. Stamps to add (positive) or to remove as a correction (negative), between -100 and 100, never 0.                                                                  |
| `oldValue` | Required. The count the caller last read. When the board has changed in between, the request is refused and nothing is applied, so a retried request can never stamp twice. |
| `remarks`  | Optional. A free comment, up to 500 characters, for example the receipt number.                                                                                             |

The response returns the new count, the goal, the state of the card (`collecting` or `goalReached`) and whether this movement reached the goal.

The request is refused, and nothing is applied, in these cases:

| Error                            | Cause                                                        | Fix                                                      |
| -------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------- |
| **Stamp count changed** (409)    | `oldValue` no longer matches the count.                      | Read the board again, then retry with the current count. |
| **Stamp target exceeded** (400)  | The stamps sent do not fit in the room left before the goal. | Send at most the number of stamps left.                  |
| **Stamp count below zero** (400) | A correction would take the count below zero.                | Correct by the current count at most.                    |
| **Stamp goal reached** (400)     | The card is full and set to **Stay full**.                   | Issue a new card for the next round.                     |
| **Not a stamp card** (404)       | The pass does not use a stamp card template.                 | Check the pass template.                                 |

See the [Stamp Card API reference](https://docs.thewalletcrew.io/api-reference/pass-management/stamp-card.md) for permissions and full payloads.

## Track stamp cards

Each stamp movement produces events that can be queried with the [Insights API](https://docs.thewalletcrew.io/developers-guides/integration-guides/insights-api.md) or sent to other tools with [webhooks](https://docs.thewalletcrew.io/developers-guides/integration-guides/webhooks.md).

| Event               | When                                                                                                         |
| ------------------- | ------------------------------------------------------------------------------------------------------------ |
| `Pass:StampApplied` | A stamp, or a correction, is recorded.                                                                       |
| `Pass:GoalReached`  | A movement reaches the goal, once per round.                                                                 |
| `Pass:StampsReset`  | The board is cleared after the goal, with **Stay full, clear on the next stamp** or **Clear straight away**. |

Events carry the count, the goal, the behavior and, for the goal, the reward benefit template, which makes it easy to measure how many holders complete a card and how long it takes.

## Common configuration errors

The template is checked on save and by the tenant configuration test. The most common messages are:

| Message                                                                        | Fix                                                                                             |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| A stamp card pass must declare its 'stamps' configuration.                     | Fill the **Stamps** card on the General tab.                                                    |
| Stamp target must be at least 1, but is N.                                     | Set **Stamps to reach the goal** between 1 and 100.                                             |
| Apple stamp image for count N is missing its strip image.                      | Add the Apple strip for that count.                                                             |
| Apple stamp image for count N is missing its poster artwork.                   | Add the poster artwork for that count, or switch off **Use new poster layout**.                 |
| Google stamp image for count N is missing its hero image.                      | Add the Google hero for that count.                                                             |
| Apple (or Google) stamp image declares count N, which the card never displays. | Remove the extra image, often left after lowering the goal or choosing **Clear straight away**. |

## FAQ

<details>

<summary><strong>Does the holder receive a notification when a stamp is added?</strong></summary>

Each stamp updates the pass in the wallet. To send a message, for example when the goal is reached, use an automation or a notification on the pass. The reward benefit itself appears on the pass and on the benefits page.

</details>

<details>

<summary><strong>Can a theme change the look of a stamp card?</strong></summary>

Yes. A [theme](https://docs.thewalletcrew.io/configure/advanced-configuration/wallet/wallet-pass-themes.md) can change the colors and images of a stamp card, for example for a seasonal design. [Which positions apply to which pass](https://docs.thewalletcrew.io/configure/advanced-configuration/wallet/wallet-pass-themes.md#which-positions-apply-to-which-pass) shows which positions apply to stamp cards. Themes are in beta: switch on **Beta features** in the profile menu to see **Wallet → Themes**.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/guides-design/design/stamp-card.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
