# Privilege 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](https://docs.thewalletcrew.io/engage-and-animate/privilege-and-activation/activation). They can also be created **externally** through connectors like [SFMC](https://docs.thewalletcrew.io/connect/marketing-automation/salesforce-marketing-cloud) or [Bloomreach](https://docs.thewalletcrew.io/connect/marketing-automation/bloomreach) or either directly via [API](https://docs.thewalletcrew.io/engage-and-animate/privilege-and-activation/broken-reference). 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 | Property | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `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. | {% hint style="info" %} Keep priorities simple. Use a small range like `0–100`. {% endhint %} ### Type The platform supports four privilege types. Each type defines how and when a privilege can be used.
4 different type of privileges
{% tabs %} {% tab title="OneTime" %} A **OneTime** privilege can be used **only once**. Once redeemed, it is consumed and cannot be used again. {% hint style="success" %} **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. {% endhint %} {% endtab %} {% tab title="Unlimited" %} An **Unlimited** privilege can be used **as many times as needed** while valid. It is never consumed. {% hint style="success" %} **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. {% endhint %} {% endtab %} {% tab title="MultiUse" %} A **MultiUse** privilege can be used a **limited number of times**. Each use reduces the remaining count until the privilege is consumed. {% hint style="success" %} **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. {% endhint %} {% endtab %} {% tab title="Unlockable" %} An **Unlockable** privilege becomes available **after progress is completed**. It is locked until the required steps are done. {% hint style="success" %} **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). {% endhint %} {% endtab %} {% endtabs %} ### Appearance | Property | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `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). | {% hint style="info" %} Images are automatically resized to match Apple Wallet and Google Wallet constraints. Use a wide image. Recommended size: `1200px × 400px`. {% endhint %} {% tabs fullWidth="false" %} {% tab title="Apple Wallet" %} 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.
Example of pass privilege appearance for apple wallet
{% hint style="info" %} Poster-style event tickets may map images differently depending on your template. If you need exact slot mapping, check your pass template configuration. {% endhint %} {% hint style="warning" %} `thumbnail` is not available for Apple. {% endhint %} {% endtab %} {% tab title="Google Wallet" %} Shown as the privilege visual when the pass template supports it. {% hint style="danger" %} TODO {% endhint %} {% endtab %} {% tab title="Pass preview" %} Displayed as the privilege main image in the preview UI. {% hint style="danger" %} TODO {% endhint %} {% endtab %} {% tab title="Crew check" %} {% hint style="danger" %} TODO {% endhint %} {% endtab %} {% endtabs %} ### Content | Property | Description | | ------------- | ------------------------------------------------------------------------------------------------------------ | | `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. | {% tabs %} {% tab title="Apple Wallet" %} {% hint style="danger" %} TODO {% endhint %} {% endtab %} {% tab title="Google Wallet" %} {% hint style="danger" %} TODO {% endhint %} {% endtab %} {% tab title="Pass preview" %} {% hint style="danger" %} TODO {% endhint %} {% endtab %} {% tab title="Crew check" %} {% hint style="danger" %} TODO {% endhint %} {% endtab %} {% endtabs %} ### Links | Property | Description | | ------------------ | ------------------------------------------------------------------------------------------------- | | `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. | {% hint style="info" %} Links are usually modeled as `{ "label": "...", "url": "https://..." }`. Exact rendering depends on the pass template. {% endhint %} {% tabs %} {% tab title="Apple Wallet" %} Shown as the primary privilege action when supported. {% endtab %} {% tab title="Google Wallet" %} Shown as the primary privilege action when supported. {% endtab %} {% tab title="Pass preview" %} Shown as a primary button. {% endtab %} {% tab title="Crew check" %} Shown as an action button for operators. {% endtab %} {% endtabs %} ### Data Use **data** when the privilege carries a redeemable balance, progress, or a code. | Property | Type | Description | | ----------- | ------------ | ----------------------------------------------- | | `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. | {% hint style="info" %} Redemption logic is enforced by the consuming system (POS, scanners, apps). The platform stores movements and computes `movementValue`. {% endhint %} #### Movement | Property | Type | Description | | ------------ | ----------------- | ---------------------------------------------------------------------------------------- | | `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). | {% hint style="info" %} Your app should check `movementValue` before redeeming. Avoid concurrent redeems on the same pass/privilege. {% endhint %} #### Examples {% tabs %} {% tab title="OneTime" %} **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):
datevalueremarkstotal
2025-01-121privilege applied1
2025-01-15-1privilege redeemed0
2025-01-151rollback1
{% endtab %} {% tab title="Unlimited" %} **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:
datevalueremarkstotal
2025-01-12-1privilege used-1
2025-01-15-2privilege used twice-3
{% endtab %} {% tab title="MultiUse" %} **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):
datevalueremarkstotal
2025-01-1210purchase 10-entry card10
2025-01-15-1consume 1 entry9
2025-01-17-4consume 4 entries (with friends)5
2025-01-171gifted 1 entry6
{% endtab %} {% tab title="Unlockable" %} **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):
datevalueremarkstotal
2025-01-120.2buy 2 pizzas0.2
2025-01-150.5buy 5 pizzas0.7
2025-01-170.4buy 4 pizzas1.1
2025-01-17-1redeem 1 pizza0.1
{% endtab %} {% endtabs %} ## 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](https://docs.thewalletcrew.io/scan/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.
Can I “undo” a redemption? Yes, if your process supports it. Instead of editing history, add a new movement that compensates the previous debit (a rollback credit) so the audit trail stays intact.
What does deletionDate do? It schedules when the privilege is deleted from the system. After deletion, it no longer affects pass rendering and should no longer be considered during scans and redemption.