> 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-animation/engage-and-animate/benefit-templates.md).

# Benefit templates

Create benefit templates: one-time, unlimited and multi-use benefits shown on wallet passes, the benefits page and Pass Scanner.

A benefit is something a pass holder can use: a free drink, a member discount, a pack of workshop sessions, a birthday gift. A benefit template is the reusable definition behind it. It is configured once in the admin console, then granted to as many passes as needed, by hand, by an automation, when a stamp card is full, or through the API.

Benefits live next to the pass rather than inside its pass template. They can be granted, used, extended or removed at any time without issuing a new pass, and every change is pushed to Apple Wallet and Google Wallet through the usual update pipeline. This makes benefit templates the main tool for turning a static card or ticket into a program that rewards, surprises and brings customers back.

{% hint style="info" %}
A benefit was formerly called a *privilege*, and the bulk mechanism called an *activation* is now an [automation](https://docs.thewalletcrew.io/guides-animation/engage-and-animate/automatisation.md) with the **Grant a benefit** action. Integrators find the full mapping in [Migrate from the privilege API](https://docs.thewalletcrew.io/developers-guides/integration-guides/wallet/pass-lifecycle.md#migrate-from-the-privilege-api).
{% endhint %}

<details>

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

* **Coffee shop:** a stamp card grants a one-time "Free drink of your choice" when the tenth stamp is collected. The barista uses it from Pass Scanner.
* **Retail loyalty:** every member carries an unlimited "10% off every order" benefit, shown on the back of the card and on the benefits page.
* **Workshops and classes:** a multi-use "5 barista workshops" pack counts down one use per session.
* **Birthday program:** an automation grants a "Birthday gift" two days before the birth date, valid 30 days from the moment it is received.
* **Events:** a VIP ticket holder receives "2 drinks at the bar", usable only during the event dates.
* **E-commerce promotion:** a shared promo code `SUMMER20` is shown to every holder, together with a call-to-action button to the online shop.

</details>

## How benefits work

A benefit template describes the rules: what the holder reads, how many times the benefit can be used, how long it stays valid, where it is shown and whether it carries a code. Granting the template to a pass creates a **benefit** on that pass, which is a copy of the template at that moment, with its own balance, validity dates and code.

Because each pass holds its own copy, changing a template does not silently rewrite what holders already have. Changes apply to benefits granted from then on. To reach existing holders, use [Save and update benefits](#edit-duplicate-deactivate-or-delete-a-template).

```mermaid
flowchart LR
    T["Benefit template<br/>(rules, content, validity, code)"]
    T -->|Admin console| B
    T -->|Automation: Grant a benefit| B
    T -->|Stamp card goal reached| B
    T -->|API| B
    B["Benefit on one pass<br/>(balance, dates, code)"]
    B --> AW["Apple Wallet<br/>back field, strip image"]
    B --> GW["Google Wallet<br/>message, hero image"]
    B --> BP["Benefits page<br/>of the pass"]
    B --> PS["Pass Scanner<br/>staff use it"]
```

### Behavior: one time, unlimited or multi-use

The behavior decides how a benefit is consumed. It is chosen when the template is created and **cannot be changed later**, because benefits already granted rely on it. To change the behavior, duplicate the template and change it on the copy.

| Behavior      | What it means                                                                     | Typical use                                          |
| ------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------- |
| **One time**  | Used once, then spent.                                                            | Free drink, welcome gift, single voucher code.       |
| **Unlimited** | Always available. Uses are counted for reporting but never run out.               | Member discount, free delivery, priority access.     |
| **Multi-use** | A set number of uses (**Number of uses**, 1 or more), counted down one at a time. | 5 workshop sessions, 10 gym entries, 3 guest passes. |

A multi-use benefit can be credited again, for example when a use is given back after a mistake, but never above its initial number of uses.

### Category

The optional category is used for reporting. It never changes how the benefit behaves.

| Category     | Description                                                                                               |
| ------------ | --------------------------------------------------------------------------------------------------------- |
| Discount     | A price reduction applied at checkout, for example -20% on the next order.                                |
| Free product | A complimentary item given once, for example a 30 ml hand cream.                                          |
| Service      | A recurring service included with membership, for example free gift wrapping in store.                    |
| Access       | Entry to a space or a set number of sessions, for example a members' lounge or 5 workshop sessions.       |
| Gift card    | A balance to spend across several visits, for example a €50 card. Available for multi-use templates only. |
| Other        | Anything that does not fit the categories above. A template without a category is reported as Other.      |

### Status of a benefit

Each benefit on a pass has a status computed from its dates and its balance. The status drives what the holder sees and whether staff can use the benefit.

| Status        | Meaning                                                                                          |
| ------------- | ------------------------------------------------------------------------------------------------ |
| **Scheduled** | Granted, but not usable yet: its **Usable from** date is in the future.                          |
| **Available** | Usable now.                                                                                      |
| **Used**      | Nothing left to use. An unlimited benefit never reaches this status.                             |
| **Expired**   | Its validity has ended. It stays visible on the pass, shown as expired, until it is removed.     |
| **Removed**   | Taken off the pass. It no longer appears to the holder, on the benefits page or in Pass Scanner. |

### Limits

A pass carries at most **20 live benefits**. Apple Wallet and Google Wallet only offer a finite number of fields and messages, so the limit keeps every pass readable. Expired benefits still count until they are removed, which is why choosing a removal rule matters for long-running programs. Granting a template to a pass that already holds a benefit from that template updates the existing benefit instead of adding a second one, and is never refused because of the limit. To offer the same perk twice, use a multi-use template or two templates.

## Where a benefit appears

The same benefit can be shown in several places. Each place is switched on or off in the template, so a benefit can be visible to the holder only, to staff only, or both.

| Surface           | What is shown                                                                                                                                            | Controlled by                                                                           |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **Benefits page** | The page on the pass that lists every benefit the holder has: visual, title, description, code, links and, when configured, an **Add to Wallet** button. | **Show on the benefits page**                                                           |
| **Apple Wallet**  | A back field whose label is the title and whose value is the description. The visual can replace the strip image of the pass.                            | **Add the description to the back of the pass**, **Use the visual as the pass artwork** |
| **Google Wallet** | A message on the pass, with the title as header and the description as body. The visual can replace the hero image.                                      | **Add the description to the back of the pass**, **Use the visual as the pass artwork** |
| **Pass Scanner**  | The benefit in the list staff see when they scan the holder's pass, with a button to use it.                                                             | **Show in Pass Scanner**, **Use automatically on scan**                                 |
| **Linked pass**   | A separate wallet pass built from an offer pass template, which the holder saves from the benefits page.                                                 | **Show an "Add to Wallet" button**                                                      |

{% hint style="warning" %}
A benefit is not device-specific. Every benefit granted to a pass is rendered on both Apple Wallet and Google Wallet. Use one benefit per campaign, with translated content, rather than one benefit per language or per wallet.
{% endhint %}

## Create a benefit template

Benefit templates are managed from **Engagement → Benefit templates**.

{% hint style="info" %}
**Engagement → Benefit templates** is a beta feature. The menu entry shows when **Beta features** is turned on in the profile menu of the admin console.
{% endhint %}

The gallery shows each template with its visual, title, behavior, tags and the number of passes it is linked to. The **Active**, **Inactive** and **Ended** filters separate templates that can be granted today from those switched off or past their end date.

<figure><img src="https://2685221786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F97ZAXMtqOjhvBBCfpmcE%2Fuploads%2Fgit-blob-6f778d257bc89e8dee233b054ab3e6c0a8fbd23d%2Fbenefit-templates-gallery-native.png?alt=media" alt="The Benefit templates gallery shows each template&#x27;s visual, behavior, tags and number of linked passes."><figcaption><p>The Benefit templates gallery shows each template's visual, behavior, tags and number of linked passes.</p></figcaption></figure>

To create one, click **Add new**, click **Name this benefit template** to give it an internal name, pick the behavior, then work through the sections below from top to bottom and click **Save**. The summary line under the name updates as the template is configured, for example "One use, then it is spent, usable for 30 days after it is granted." The template is **Active** by default and can be granted straight away.

<p align="center"><a href="https://admin.thewalletcrew.io/tenant/~/engagement/benefit-templates" class="button secondary" data-icon="chevrons-right">Open Benefit templates in the admin console</a></p>

Viewing benefit templates needs the permission `tenant.configuration.benefitTemplate:read`; creating and editing them needs `tenant.configuration.benefitTemplate:write`.

<figure><img src="https://2685221786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F97ZAXMtqOjhvBBCfpmcE%2Fuploads%2Fgit-blob-afac19648bade9048ecf661eb815af89b98f1aba%2Fbenefit-template-editor-behavior-content-native.png?alt=media" alt="The top of the editor sets the name, tags, behavior, category and the content the holder reads."><figcaption><p>The top of the editor sets the name, tags, behavior, category and the content the holder reads.</p></figcaption></figure>

### Name, tags and status

The name is internal: holders never see it. It is used in the admin console, in automations and in Pass Scanner profiles. The template identifier is derived from the name when the template is first saved. It may contain letters, digits, hyphens and underscores, must start with a letter or a digit, is limited to 128 characters, and cannot be changed afterwards.

Tags are free labels used to filter reports and to build [Pass Scanner profiles](https://docs.thewalletcrew.io/guides-scan/scan/pass-scanner/pass-scanner-profiles.md). They are never shown to the holder.

The **Active** switch controls whether the template can be granted. An inactive template can no longer be granted, but holders who already have its benefit keep it.

### How it works

Pick the **Behavior** (see [Behavior](#behavior-one-time-unlimited-or-multi-use)), the **Number of uses** for a multi-use template, and an optional **Category** (see [Category](#category)).

### What the customer sees

| Setting         | Description                                                                                                                              |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Title**       | Required. What the holder reads first, up to 200 characters, for example "Free drink of your choice".                                    |
| **Description** | Optional supporting text, up to 2,000 characters. Use it for conditions: where, when, how.                                               |
| **Language**    | Switches between the default text and each language of the tenant. A field left empty in a language falls back to the default version.   |
| **Visual**      | Optional image, uploaded (PNG, JPEG, GIF or WebP) or referenced by a full `https://` address. The recommended size is **1200 × 400 px**. |

On Google Wallet, the visual becomes the hero image and is cropped to fit the hero area, so keep important content centered. Translated content is used on Apple Wallet and Google Wallet according to the language of the holder's phone.

### Validity

Validity defines when the benefit can be used. All times are entered in the time zone of the computer used in the admin console.

| Setting         | Options                                                                                                                                                                                                                                            |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Usable from** | Empty means straight away. A future date makes granted benefits **Scheduled** until then.                                                                                                                                                          |
| **Until**       | **No end**: usable for as long as it is active. **A date**: the same end date for every holder, whenever they received it. **A duration**: counted from the moment each holder receives it, for example 30 days, so everyone gets the same window. |

<figure><img src="https://2685221786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F97ZAXMtqOjhvBBCfpmcE%2Fuploads%2Fgit-blob-52b3dfe009a7ea628aabd050f6e8d57aeaa83654%2Fbenefit-template-validity-card-native.png?alt=media" alt="The Validity card with a duration of 30 days, which gives every holder the same window from the moment they receive the benefit"><figcaption><p>A duration-based validity gives every holder the same 30-day window from the moment they receive the benefit.</p></figcaption></figure>

{% hint style="info" %}
An end date in the past is accepted, but anything granted from the template then arrives already expired. The editor warns about it.
{% endhint %}

### Where the customer finds it

| Setting                            | Description                                                                                                                                                                                                                                                      |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Show on the benefits page**      | Lists the benefit on the page of the pass that shows every benefit the holder has. On by default.                                                                                                                                                                |
| **Show an "Add to Wallet" button** | Lets the holder save the benefit as a pass of its own, built from an **offer** pass template chosen in the editor. Useful for gift cards or invitations that must live separately in the wallet. On Google Wallet, the linked pass is attached to the main pass. |

### How your staff use it

| Setting                       | Description                                                                                                                                                              |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Show in Pass Scanner**      | Staff find the benefit and use it when they scan the holder's pass. On by default.                                                                                       |
| **Use automatically on scan** | Each scan of the pass uses the benefit straight away, with no tap. A second scan within the profile's repeat-scan block takes no use. Requires **Show in Pass Scanner**. |

### Advanced settings

#### On the pass

| Setting                                         | Description                                                                                                                                                        |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Use the visual as the pass artwork**          | Replaces the strip image on Apple Wallet and the hero image on Google Wallet with the benefit visual. When several benefits ask for it, the highest priority wins. |
| **Add the description to the back of the pass** | Adds the title and description as a back field on Apple Wallet and as a message on Google Wallet.                                                                  |
| **Priority**                                    | A whole number. Higher values are displayed first on the pass and win the pass artwork.                                                                            |

#### Removal from the pass

Removal decides when a benefit leaves the pass. Removing it frees one of the pass's 20 slots and takes it off the benefits page and out of Pass Scanner.

| Option                                | Behavior                                                                                                                                     |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Never — removed by hand**           | It stays on the pass once it stops working, shown as expired, until someone removes it.                                                      |
| **At the end of validity**            | It leaves the pass the moment it stops being usable.                                                                                         |
| **A while after the end of validity** | It stays visible, expired, for a number of days (1 to 3,650), long enough for the holder to understand why it no longer works.               |
| **On a date of its own**              | It leaves every pass on a chosen date, which must be on or after the end of validity. Useful to clear a campaign on a chosen operating date. |

#### Code

**Give each benefit a code** adds a value to show at the till or type in online.

| Setting                                                                               | Description                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Format**                                                                            | **QR code**, **Code 128**, **EAN-13**, **PDF417**, **Aztec**, **Data Matrix**, **Code 39**, **Raw** (text only, no barcode), or **No barcode**.                                                                                                                                                                                                                           |
| **Attribution**                                                                       | **Shared**: one value for every holder, which works for an e-commerce promo code but never for a face-value voucher. **Auto-generated**: a different value for every benefit granted, drawn from a pattern; the only acceptable choice for a face-value voucher. **Custom script**: a unique value returned by a script, for example a code reserved in a partner system. |
| **Shared code**                                                                       | The value shown to every holder when attribution is Shared.                                                                                                                                                                                                                                                                                                               |
| **Length**, **Character set**, **Prefix**, **Suffix**, **Generate codes in capitals** | The pattern of auto-generated codes. The prefix and suffix sit outside the generated part, so a length of 10 with prefix `GIFT-` gives `GIFT-` followed by 10 characters.                                                                                                                                                                                                 |

| Character set          | Characters | Minimum length |
| ---------------------- | ---------- | -------------- |
| Alphanumeric (default) | A–Z, 0–9   | 6              |
| Numeric                | 0–9        | 9              |
| Letters only           | A–Z        | 7              |
| Hex                    | 0–9, A–F   | 8              |

Auto-generated codes are at most 64 characters long. An auto-generated EAN-13 code uses digits only and must be exactly 12 digits long, prefix and suffix included; a shared EAN-13 code must contain 12 or 13 digits.

<figure><img src="https://2685221786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F97ZAXMtqOjhvBBCfpmcE%2Fuploads%2Fgit-blob-5fb1d9b2b6476b7e2f01cbbc158b4dc845d0296b%2Fbenefit-template-advanced-code-retake.png?alt=media" alt="Advanced settings: the Code card gives each benefit an auto-generated EAN-13 code of 12 digits"><figcaption><p>Advanced settings: every benefit gets its own auto-generated code, here an EAN-13 of 12 digits.</p></figcaption></figure>

#### Links

Links are shown on the benefits page only.

| Setting            | Description                                                                                                    |
| ------------------ | -------------------------------------------------------------------------------------------------------------- |
| **Call to action** | A button on the benefit that opens a page of the brand. Give the button a label: without one, it is not shown. |
| **Terms link**     | A link to the terms, in small print under the button.                                                          |

Links must be full `https://` addresses, and labels are limited to 100 characters.

## Edit, duplicate, deactivate or delete a template

Editing a template changes the benefits granted from then on. Holders keep the copy they were given, number of uses included, until the template is granted to them again. To carry a change to existing holders, use **Save and update benefits**: each granted benefit is rewritten from the template, uses already taken and codes already issued are kept, and validity dates are recalculated, so a shorter validity can end some benefits right away. Benefits already used or expired are left as they are, and passes are updated gradually in the background. The option is not available when the template's linked pass template has changed.

Choosing **Save and update benefits** opens a confirmation that shows how many benefits have been granted from the template and what the update does to them. **Save and update** confirms; **Cancel** goes back to the editor without saving.

<figure><img src="https://2685221786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F97ZAXMtqOjhvBBCfpmcE%2Fuploads%2Fgit-blob-c29c854ef1297839d27ba2fa044537ebcde3ab07%2Fbenefit-template-update-granted-dialog-native.png?alt=media" alt="Saving a template that is already granted offers to rewrite the benefits holders already have."><figcaption><p>Saving a template that is already granted offers to rewrite the benefits holders already have.</p></figcaption></figure>

The **Granted benefits** tab of a template shows the benefits granted from it, which helps check the reach of a change before saving.

**Duplicate** creates a copy named "(copy)", which is the quickest way to change a behavior that is locked on the original.

Switching a template to **Inactive** stops new grants without touching existing benefits. A template can only be **deleted** when no live benefit comes from it and no enabled automation grants it: remove or let the benefits expire, and disable or change those automations first. Deleting a template also deletes its images.

## Check the setup

Before granting a template to real holders, a quick test on a QA pass avoids most support requests:

1. Grant the template to a test pass from the pass page (see [Grant and use benefits](https://docs.thewalletcrew.io/guides-animation/engage-and-animate/benefit-templates/grant-and-use-benefits.md)).
2. Open the pass on an iPhone and an Android phone: check the back field or message, the artwork, and the translated texts.
3. Open the benefits page from the pass and check the visual, the code and the links.
4. Scan the pass with Pass Scanner and use the benefit once. Check that the status and the uses left update on the pass page.
5. Check the validity dates shown on the pass page match the expected window.

## FAQ

<details>

<summary><strong>Can one benefit show a different image per language?</strong></summary>

Yes. Add a translated visual in each language. Apple Wallet picks the image matching the phone language and falls back to the default image; Google Wallet uses the default image.

</details>

<details>

<summary><strong>Why does the benefit not appear on the pass?</strong></summary>

Check that the template is **Active**, that the benefit is not **Scheduled** or **Removed** on the pass page, and that at least one surface in [Where a benefit appears](#where-a-benefit-appears) is switched on. A benefit with every surface switched off is visible nowhere.

</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-animation/engage-and-animate/benefit-templates.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.
