Privilege
Define and manage pass privileges (perks) in The Wallet Crew: types, creation sources, priority rules, and movement-based redemption state.
A privilege is a benefit attached to a single digital pass. It defines what the holder can do, claim, or unlock. Privileges are separate from the pass itself. You can add, update, or remove them without re-issuing the pass.
Why privileges matter
Privileges matter because they transform a simple pass into a powerful tool for engagement and loyalty. A pass alone gives access, but a privilege adds a reason for customers to care, interact, and come back. It’s the difference between a standard ticket and an experience that feels personal, rewarding, and memorable.
They matter for marketing because they create opportunities to delight customers, drive incremental revenue, and encourage behaviors that benefit the brand. By offering extras like discounts, free items, or exclusive perks, privileges make each interaction more valuable and strengthen the relationship between the customer and the brand.
Finally, privileges give flexibility and creativity to campaigns. Brands can craft unique combinations of benefits, target different customer segments, or add limited-time rewards, all without changing the core pass. This makes it easier to innovate, test ideas, and deliver moments that turn ordinary access into meaningful experiences.
How privileges behave
Privileges have a behavioral type:
OneTime: redeem once, then it’s gone.
Unlimited: always available while valid.
MultiUse: limited number of uses.
Unlockable: appears only after progress or conditions are met.
This maps directly to real perks. Free drink, 10% discount, 5 entries, spend-to-unlock rewards.
How privileges get onto a pass
Privileges are created in various ways. They can be generated internally by the platform through activations. They can also be created externally through connectors like SFMC or Bloomreach or either directly via API.
A pass can carry up to 5 privileges at the same time. Conflicts use priority, then most recent update as tie-breaker.
Privilege Definition
A privilege is a structured object. It groups metadata, appearance, content, links, and value/status.
General properties
privilegeId
Unique identifier of the privilege. Auto-generated by the system.
priority
Integer used to resolve conflicts when multiple privileges modify the same property. Higher wins. If equal, last update wins.
type
One of OneTime, Unlimited, MultiUse, Unlockable.
tags
List of tags used for reporting.
origin.generator
(optional) Name of the process generating the privilege. Use internal for platform activations.
origin.activationId
(optional) Identifier of the generating process. Example: internal activation id, or an external journeyId (SFMC).
origin.externalId
(optional) Unique identifier of this privilege in an external system.
deletionDate
Date when the privilege will be deleted from the system. Once deleted, it no longer affects pass rendering.
Keep priorities simple. Use a small range like 0–100.
Type
The platform supports four privilege types. Each type defines how and when a privilege can be used.
A OneTime privilege can be used only once. Once redeemed, it is consumed and cannot be used again.
Real-world use cases
Coffee shop: “Free espresso” voucher, redeem once.
Event: “VIP lounge entry” for one attendee, 1 scan only.
Retail: “$15 off your next order” code, usable once.
An Unlimited privilege can be used as many times as needed while valid. It is never consumed.
Real-world use cases
Membership: “Free shipping” on every online order.
Retail: “10% off all purchases” during the whole season.
Service: “Priority support” available for every ticket submission.
A MultiUse privilege can be used a limited number of times. Each use reduces the remaining count until the privilege is consumed.
Real-world use cases
Gym: “10 entries” pack, each check-in consumes 1.
Venue: “3 guest passes”, each guest scan consumes 1.
Car wash: “5 washes”, each wash consumes 1.
An Unlockable privilege becomes available after progress is completed. It is locked until the required steps are done.
Real-world use cases
Restaurant: “Buy 10 pizzas, get 1 free” (progress unlocks the reward).
Coffee shop: “Collect 8 stamps, get 1 free” (each purchase increments progress).
Education: “Complete 3 modules, unlock exam voucher” (progress from LMS events).
Appearance
mainImage
(optional, localizable) Main image of the privilege. Use it to explain the benefit visually. Keep it readable at small sizes.
thumbnail
(optional, localizable) Small image for compact UIs. Use a simple pictogram or logo-style asset.
backgroundColor
(optional) Background color override for privilege UI elements (when supported).
foregroundColor
(optional) Foreground/text color override for privilege UI elements (when supported).
Images are automatically resized to match Apple Wallet and Google Wallet constraints. Use a wide image. Recommended size: 1200px × 400px.
Will override the main image of the pass.
If the property contains localized values, the phone language selects the localized version. If no localized version exists, default is used.
Poster-style event tickets may map images differently depending on your template. If you need exact slot mapping, check your pass template configuration.
thumbnail is not available for Apple.
Shown as the privilege visual when the pass template supports it.
TODO
Displayed as the privilege main image in the preview UI.
TODO
TODO
Content
title
(optional, localizable) Short label for the privilege. Example: VIP Lounge Access, -10%, Free drink.
description
(optional, localizable) Supporting text for users and operators. Use it for conditions and constraints.
TODO
TODO
TODO
TODO
Links
legalInformation
(optional, localizable) Terms and conditions related to the privilege. Typically a label + URL.
callToAction
(optional, localizable) Primary action for the privilege. Typically a label + URL.
Links are usually modeled as { "label": "...", "url": "https://..." }. Exact rendering depends on the pass template.
Shown as the primary privilege action when supported.
Shown as the primary privilege action when supported.
Shown as a primary button.
Shown as an action button for operators.
Data
Use data when the privilege carries a redeemable balance, progress, or a code.
value
decimal
Computed value. Sum of all movements[].value.
movements
movement[]
List of value movements (credits/debits).
content
string
Free-form value. Example: promo code.
Redemption logic is enforced by the consuming system (POS, scanners, apps). The platform stores movements and computes movementValue.
Movement
movementId
unique identifier
Generated by the platform.
date
dateTime
Date when this movement happened.
remarks
string
Free-form remark (audit/debug).
value
decimal
Can be negative when the privilege is used. Can be fractional for progress (Unlockable).
Your app should check movementValue before redeeming. Avoid concurrent redeems on the same pass/privilege.
Examples
Use cases
Concert: “1 free welcome drink” for VIP tickets.
Retail: “1 free gift wrap” on the next purchase.
Museum: “1 guided tour entry” for a specific date.
Movement timeline (example: VIP welcome drink):
2025-01-12
1
privilege applied
1
2025-01-15
-1
privilege redeemed
0
2025-01-15
1
rollback
1
Use cases
Loyalty tier: “10% discount” every time, while tier is active.
Airline: “1 free checked bag” on every flight segment.
Subscription: “Unlimited access” to premium content.
For Unlimited privileges, movements are often omitted because nothing is “consumed”. If you still store movements for audit (optional), it can look like this:
2025-01-12
-1
privilege used
-1
2025-01-15
-2
privilege used twice
-3
Use cases
Gym: “10 entries” prepaid pack.
Festival: “5 drink tokens” linked to the ticket.
Parking: “20 exits” pack for a company parking card.
Movement timeline (example: gym 10-entry pack):
2025-01-12
10
purchase 10-entry card
10
2025-01-15
-1
consume 1 entry
9
2025-01-17
-4
consume 4 entries (with friends)
5
2025-01-17
1
gifted 1 entry
6
Use cases
Restaurant: buy 10 pizzas, unlock 1 free pizza.
Coffee shop: collect 8 stamps, unlock 1 free drink.
Retail: spend $200 in a month, unlock $20 voucher.
Movement timeline (example: buy 10 pizzas, unlock 1 free):
2025-01-12
0.2
buy 2 pizzas
0.2
2025-01-15
0.5
buy 5 pizzas
0.7
2025-01-17
0.4
buy 4 pizzas
1.1
2025-01-17
-1
redeem 1 pizza
0.1
Real-world use case
Use privileges when you need stateful perks on a pass. Native wallet app will automatically display privilege information. For greater experience, it is also possible to use our Crew Check application to scan passes and list and redeem privilege.
Event ticket
Turn a static ticket into a live campaign surface. Keep one pass for entry, then add perks as the event unfolds. Use OneTime for single-claim perks (VIP lounge entry, fast-lane access, welcome drink), MultiUse for token packs (drink tokens, cloakroom credits), and Unlockable for perks that appear after progress.
Example: everyone enters with the same pass, but an Unlockable “Afterparty access” privilege appears after the third scan. A MultiUse “5 drink tokens” privilege is added at doors open and decremented at the bar.
Loyalty card
Run promos and tier benefits without changing the card. Let CRM, CDP, or POS update perks as customers progress.
Use Unlimited for always-on entitlements (tier discounts, free shipping, priority support). Use Unlockable for spend triggers, MultiUse for counters (stamps, entries), and OneTime for single-hit rewards (birthday, recovery).
Example: give VIP customers an Unlimited “15% off” privilege with higher priority than campaign discounts. When the customer spends €200 in a month, your CDP adds an Unlockable “€20 voucher” privilege, and the POS redeems it once.
Gift card
Use privileges when the card needs redeemable value, a code, or both.
Store a balance as MultiUse and decrement it with movements per spend. Store a promo code as OneTime and consume it at first use.
Example: start a gift card at +50. A €12 purchase adds a -12 movement and leaves 38. A holiday promo adds a +10 top-up movement. If that purchase is refunded, add a +12 rollback movement instead of editing history.
Redemption is enforced by your POS or checkout. The platform stores state and movements for reporting.
Membership
Use a pass as a membership surface with changing entitlements.
Use Unlimited for ongoing access, MultiUse for monthly quotas, OneTime for single claims, and Unlockable for milestone rewards.
Example: a coworking pass has Unlimited “premium access” plus MultiUse “5 day passes” that reset monthly. After onboarding is completed, an Unlockable “1:1 session” privilege becomes redeemable in the booking flow.
FAQ
How many privileges can a pass have at the same time?
You can attach up to 5 privileges to a single pass at the same time. If you need more benefits, group them into fewer privileges, or rotate them over time.
What happens when multiple privileges conflict?
When multiple privileges try to modify the same property, priority decides the winner. If priorities are equal, the most recently updated privilege wins.
Do I need to re-issue the pass when a privilege changes?
No. Privileges are separate from the pass core data. You can add, update, or remove a privilege without re-issuing the pass.
Where do privileges come from?
You can create privileges internally using activations, or externally through connectors (for example SFMC or Bloomreach). You can also create and update them directly via the API.
How is redemption state stored for MultiUse and OneTime privileges?
Use movements to track credits and debits. The platform stores the movement history and computes the current value, but your consuming system (POS, scanners, app) enforces the redemption rules.
Last updated