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

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

Opening a benefit shows where it came from, its usage history and the actions available on it.
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.

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

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:
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.
{{ 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
Last updated

