Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 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 with the Grant a benefit action.

Stamp card

Rewards earned by collecting stamps.

Reward benefit template on a stamp card template.

API

Grants driven by a CRM, a loyalty engine, a POS or an e-commerce platform.

Bulk file

Large one-off grants from a file.

Benefit template column of the flat-file pass update.

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 or the benefit provider script.

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.

1

Open the pass

Open Wallet → Passes, find the pass, then open its Benefits tab.

2

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.

3

Confirm

Click Grant a benefit. The pass is updated in the holder's wallet straight away.

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

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.

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

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.

The Benefits tab of a pass shows each benefit's status, behavior, uses left and validity.
The Benefits tab of a pass shows each benefit's status, behavior, uses left and validity.

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.

A benefit's page shows its origin, its usage history and the actions to give back, adjust, change the code or extend it.
A benefit's page shows its origin, its usage history and the actions to give back, adjust, change the code or extend it.

Use a benefit at the counter

Pass Scanner 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 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.

Track benefits

Analytics → Benefits shows how benefits perform over a chosen period: see Analytics dashboards.

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

Benefit analytics shows uses, engaged passes and new benefits, with the top benefit templates of the period.
Benefit analytics shows uses, engaged passes and new benefits, with the top benefit templates of the period.

Every change is also an event that can be queried with the Insights API or sent to other tools with webhooks. The events of a benefit on a pass are listed in the 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 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 in the Developers guides.

FAQ

Why was the benefit not granted by the automation?

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 cannot receive a new one. Also check that the pass matched the automation's audience at that time.

Does granting the same template twice create two benefits?

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.

Last updated