> 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/grant-and-use-benefits.md).

# Grant and use benefits

Grant benefits to wallet passes from the console, automations, stamp cards or the API, use them with Pass Scanner, and track them in analytics.

A [benefit template](https://docs.thewalletcrew.io/guides-animation/engage-and-animate/benefit-templates.md) only becomes useful once it is granted to passes. This page covers every way a benefit reaches a pass, how staff and the admin console use it, and how to follow its performance.

## Ways to grant a benefit

| Channel        | Best for                                                                                                                | Where to configure it                                                                                                                                                                                                                      |
| -------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Console**    | One pass at a time: tests, customer service gestures.                                                                   | Pass page → **Benefits** → **Grant a benefit**.                                                                                                                                                                                            |
| **Automation** | Campaigns and rules applied to many passes: welcome gifts, birthdays, tier upgrades, keep-watching audiences.           | [Automation](https://docs.thewalletcrew.io/guides-animation/engage-and-animate/automatisation.md) with the **Grant a benefit** action.                                                                                                     |
| **Stamp card** | Rewards earned by collecting stamps.                                                                                    | **Reward benefit template** on a [stamp card template](https://docs.thewalletcrew.io/guides-design/design/stamp-card.md).                                                                                                                  |
| **API**        | Grants driven by a CRM, a loyalty engine, a POS or an e-commerce platform.                                              | [Benefits API](https://docs.thewalletcrew.io/api-reference/pass-management/benefits.md).                                                                                                                                                   |
| **Bulk file**  | Large one-off grants from a file.                                                                                       | Benefit template column of the [flat-file pass update](https://docs.thewalletcrew.io/configure/advanced-configuration/wallet/import-and-export/update-pass-using-flat-files.md).                                                           |
| **Connectors** | Benefits that already exist in a partner system, such as coupons from a loyalty platform, or a benefit provider script. | Connector settings, for example [Comarch](https://docs.thewalletcrew.io/connectors/crm-and-fidelity/comarch.md) or the [benefit provider script](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/benefit-provider.md). |

Benefits pushed by an integration without a template behind them are shown as **External** in the admin console.

### Grant a benefit from the console

Granting from the pass page is the fastest way to test a template or to make a one-off gesture.

{% stepper %}
{% step %}

#### Open the pass

Open **Wallet → Passes**, find the pass, then open its **Benefits** tab.
{% endstep %}

{% step %}

#### Pick the benefit template

Click **Grant a benefit**, search the template by name, and select it. The internal name is shown in gray under the title. Templates already on the pass, or not usable yet, can still be granted and are only marked; ended templates are shown grayed out because the holder would receive an expired benefit. When the selected template is already on the pass, the button reads **Refresh benefit**: granting it again updates the existing benefit from the template instead of adding a second one.
{% endstep %}

{% step %}

#### Confirm

Click **Grant a benefit**. The pass is updated in the holder's wallet straight away.
{% endstep %}
{% endstepper %}

<figure><img src="https://2685221786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F97ZAXMtqOjhvBBCfpmcE%2Fuploads%2Fgit-blob-6019a0ee02171b24016ccd70b915c03324d7ae4a%2Fpass-grant-a-benefit-dialog-retake.png?alt=media" alt="The Grant a benefit dialog shows each template&#x27;s behavior and validity, marks those already on the pass, and offers Refresh benefit for one the pass already holds."><figcaption><p>The Grant a benefit dialog shows each template's behavior and validity, marks those already on the pass, and offers Refresh benefit for one the pass already holds.</p></figcaption></figure>

{% hint style="info" %}
When no template is offered, create one first or switch an existing one back to **Active**. When the pass already carries 20 live benefits, remove an expired benefit before granting a new one. See [Limits](https://docs.thewalletcrew.io/guides-animation/engage-and-animate/benefit-templates.md#limits).
{% endhint %}

### Grant a benefit with an automation

The **Grant a benefit** action grants a template to every pass the automation targets, in the same update as the other actions of the automation (data change, theme, pass template), followed by the notification when there is one. A template that is disabled or deleted when the automation runs is skipped.

Automations can also react to benefit events (**A benefit is used**, **A benefit is credited**, **A benefit’s balance moves either way**). See [Automation](https://docs.thewalletcrew.io/guides-animation/engage-and-animate/automatisation.md) for the full editor.

### Grant a benefit through the API

Integrations grant a template to a pass, or create a free-standing benefit, with the Benefits API. Granting a template is idempotent: granting the same template again to the same pass updates the benefit it already created.

| Operation                          | Endpoint                                                                    |
| ---------------------------------- | --------------------------------------------------------------------------- |
| Grant a benefit template to a pass | `POST /api/{tenantId}/passes/{passId}/benefitTemplates/{benefitTemplateId}` |
| List the benefits of a pass        | `GET /api/{tenantId}/passes/{passId}/benefits`                              |
| Create a benefit on a pass         | `POST /api/{tenantId}/passes/{passId}/benefits`                             |
| Read, replace or delete a benefit  | `GET`, `PUT`, `DELETE /api/{tenantId}/passes/{passId}/benefits/{benefitId}` |
| Record a use or a credit           | `POST /api/{tenantId}/passes/benefits/{benefitId}/movements`                |
| List benefits across passes        | `GET /api/{tenantId}/benefits`                                              |

A movement carries a signed `value` (negative to use, positive to credit, never zero, whole numbers only) and the `oldValue` the caller last read. When the balance changed in between, the request is refused with a conflict and nothing is applied, so a retried request can never use a benefit twice. The full reference, including permissions and errors, is in the [API reference](https://docs.thewalletcrew.io/api-reference/pass-management/benefits.md).

## Manage a benefit on a pass

The **Benefits** tab of a pass lists every benefit it holds, with its status, behavior, uses left, validity and origin, for example **Console**. Each row has a **Use** button and a menu to open the benefit.

<figure><img src="https://2685221786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F97ZAXMtqOjhvBBCfpmcE%2Fuploads%2Fgit-blob-7f2efd0fa8ecbdaaaaec983d939fa9846fb9c12b%2Fpass-benefits-tab-retake.png?alt=media" alt="The Benefits tab of a pass shows each benefit&#x27;s status, behavior, uses left and validity."><figcaption><p>The Benefits tab of a pass shows each benefit's status, behavior, uses left and validity.</p></figcaption></figure>

Opening a benefit shows where it came from, its usage history and the actions available on it.

| Action                    | Effect                                                                                                                                        |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Count 1 use** / **Use** | Records one use, for example when the benefit was used at a till without Pass Scanner.                                                        |
| **Give back 1 use**       | Credits one use back after a mistake. A one-time or multi-use benefit can never go above its initial number of uses.                          |
| **Adjust the balance**    | Records a signed entry, positive to credit and negative to deduct, with a reason. It cannot take the benefit below zero and cannot be undone. |
| **Change** code           | Replaces the code of this benefit only.                                                                                                       |
| **Extend**                | Changes the validity for this holder only, without changing the template.                                                                     |
| **Remove from pass**      | Deletes the benefit from the pass and frees its slot.                                                                                         |

The title, description, visual and links of a single benefit are copied from the template when it is granted. They cannot be edited on one pass: granting the template again refreshes them.

<figure><img src="https://2685221786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F97ZAXMtqOjhvBBCfpmcE%2Fuploads%2Fgit-blob-45d78c1f19103d5ddcf167595dd64173919c516c%2Fpass-benefit-detail-page-retake.png?alt=media" alt="A benefit&#x27;s page shows its origin, its usage history and the actions to give back, adjust, change the code or extend it."><figcaption><p>A benefit's page shows its origin, its usage history and the actions to give back, adjust, change the code or extend it.</p></figcaption></figure>

## Use a benefit at the counter

[Pass Scanner](https://docs.thewalletcrew.io/guides-scan/scan/pass-scanner.md) lists the benefits of a scanned pass that have **Show in Pass Scanner** switched on, and staff tap one to use it. A [Pass Scanner profile](https://docs.thewalletcrew.io/guides-scan/scan/pass-scanner/pass-scanner-profiles.md) can narrow the list to some tags or templates, for example only bar benefits on the bar's phone. With **Use automatically on scan**, each scan uses the benefit straight away, with no tap, which speeds up queues at a bar or a cloakroom.

Every use is recorded with its source (console, Pass Scanner, API), the operator or API key and the device, and appears in the benefit's usage history.

{% hint style="warning" %}
A use taken in Pass Scanner is final at the counter. To correct a mistake, open the pass in the admin console and use **Give back 1 use**. The history keeps both entries, so reporting stays accurate.
{% endhint %}

## Track benefits

**Analytics → Benefits** shows how benefits perform over a chosen period: see [Analytics dashboards](https://docs.thewalletcrew.io/guides-monitoring/monitor/analytics-dashboards.md#benefits).

The usage rate divides uses by benefits granted. A multi-use or unlimited template can therefore go above 100%: one "5 barista workshops" pack used three times shows 300%.

<figure><img src="https://2685221786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F97ZAXMtqOjhvBBCfpmcE%2Fuploads%2Fgit-blob-0c9e6f9d9155bd63544a87a0a6d381b984627528%2Fanalytics-benefits-dashboard.png?alt=media" alt="Benefit analytics shows uses, engaged passes and new benefits, with the top benefit templates of the period."><figcaption><p>Benefit analytics shows uses, engaged passes and new benefits, with the top benefit templates of the period.</p></figcaption></figure>

Every change is also an event 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). The events of a benefit on a pass are listed in the [event reference](https://docs.thewalletcrew.io/guides-monitoring/monitor/what-the-wallet-crew-tracks.md#event-reference). Template events are:

| Event                                                                           | When                                                            |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `BenefitTemplate:Created`, `BenefitTemplate:Updated`, `BenefitTemplate:Deleted` | A template is created, changed or deleted in the admin console. |

### Show benefits in pass fields

Pass templates can display benefit data in their fields with Liquid. Each benefit is available under `benefits.<template key>`, where the key is the benefit template identifier with every character other than a letter, a digit or an underscore replaced by `_`. Counters are available under `benefitStats`.

| Variable                                                                                | Value                                                                     |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `{{ benefits.free_drink_reward.data.value }}`                                           | The balance of the benefit granted from the template `free-drink-reward`. |
| `{{ benefitStats.total }}`                                                              | Benefits on the pass, removed ones excluded.                              |
| `{{ benefitStats.active }}`                                                             | Benefits usable now.                                                      |
| `{{ benefitStats.scheduled }}`, `{{ benefitStats.used }}`, `{{ benefitStats.expired }}` | Benefits not active yet, used, or expired.                                |

See [Liquid templating](https://docs.thewalletcrew.io/developers-guides/integration-guides/wallet/templating-engine.md) for the syntax.

## Migrate from the privilege API

The former privilege endpoints are deprecated and forward to benefits. The full mapping of former and current names is in [Migrate from the privilege API](https://docs.thewalletcrew.io/developers-guides/integration-guides/wallet/pass-lifecycle.md#migrate-from-the-privilege-api) in the Developers guides.

## FAQ

<details>

<summary><strong>Why was the benefit not granted by the automation?</strong></summary>

Check the automation's execution history first. A template that is inactive or deleted when the automation runs is skipped, and a pass at the [20-benefit limit](https://docs.thewalletcrew.io/guides-animation/engage-and-animate/benefit-templates.md#limits) cannot receive a new one. Also check that the pass matched the automation's audience at that time.

</details>

<details>

<summary><strong>Does granting the same template twice create two benefits?</strong></summary>

No. Granting a template to a pass that already holds a benefit from it updates that benefit and refreshes its title, description, visual and links.

</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/grant-and-use-benefits.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.
