PRD: Entitlements - policy, target, grant & redemption
| Module | Sale | PRD ID | PRD-ENT-001 |
| Status | Ready to dev | FEAT | ENT |
| Epic | — | Plane | BANA-1519 |
| Date | 2026-06-15 | Version | v1.0 |
| Packages | @nx/sale | URD | ENT |
| Surface | Sale · POS | ||
| Owner | Phát Nguyễn | ||
TL;DR
Sell bundles and passes - coffee 10-packs, gym memberships, class bundles, metered minutes - that a customer draws down visit by visit. A policy ties a sellable variant to a quota and validity window; targets scope which items qualify; selling it mints a grant that freezes the policy at sale time so catalogue edits never alter a sold pass; each use appends a redemption to an audit ledger; reversals return quota; and the grant lifecycle (pending → active → exhausted / expired / suspended / cancelled) always tells you what's left.
Implementation status: the data model is in place - the policy, target, grant, and redemption entities (including the frozen-snapshot fields, quota total/used counters, lifecycle statuses, and redeem/reversal entry types) all exist and are persisted. The mint, redeem, and reverse behaviour described below is the target design and is not yet implemented: the entities are currently exposed only through generic create/read/update/delete, selling the entitlement variant does not yet mint a grant, and no redemption logic draws down the counter, validates scope, converts units, or reverses. The sections below describe the intended behaviour, not a shipped flow.
1. Context & Problem
A POS sells items that are consumed instantly. But merchants increasingly sell claims on future value: a prepaid drinks bundle, a membership window, a punch card, a block of service minutes. None of these fit a one-shot order line - the customer pays once and then draws the value down across many later visits, each of which must check "is there balance left, is it still valid, does it cover this item?".
Without a first-class model for this, a merchant fakes it with manual notes or discount codes - no balance tracking, no expiry, no audit of who used what when, and no protection against a sold bundle silently changing when the catalogue is edited. The result is disputes, leakage, and no way to answer "how many sessions does this customer have left?".
This increment lays the entitlements foundation as a self-contained part of the Sale module. It separates the template a merchant configures (policy + targets) from the sold instance a customer holds (grant), and models every use as an immutable redemption so the balance can be auditable and the sold terms honoured exactly as sold. To date only the data model has landed; the runtime that mints grants and applies redemptions is still to be built.
2. Goals & Non-Goals
Goals
- A policy that turns a sellable variant into an entitlement with a quota axis, a validity axis, an activation mode, and declared limit dimensions.
- Targets that scope which items a policy's grant may be redeemed against - empty scope means open access.
- A grant minted when the entitlement variant is sold, carrying a unique code, a quota balance, a resolved validity window, and a frozen policy snapshot so catalogue edits never alter a sold grant.
- A redemption ledger that draws the grant's used counter down, validates the redeemed item against the frozen scope, and supports reversals that return quota.
- A grant lifecycle - pending, active, exhausted, expired, suspended, cancelled - that always states what the holder still has.
Non-Goals
- The pricing of the entitlement variant - the price lives with the product's pricing (Product); this PRD covers what is granted, not what it costs.
- Payment capture and order checkout - owned by Orders and Payment; a grant is minted off a completed sale, it does not run the sale.
- Loyalty point earning (PNT) - a separate reward mechanic; entitlements are sold balances, not earned points.
- A customer-facing wallet UI to browse remaining balances - the balance is recorded and queryable; a dedicated end-user screen is a later increment.
3. Success Metrics
| Metric | Target / signal |
|---|---|
| Balance accuracy | A grant's available balance equals quota total minus the sum of its redemptions at all times |
| Snapshot integrity | A policy edited after a sale never changes the terms of an already-sold grant |
| Scope safety | A redemption against an item outside the grant's frozen scope is refused (unless scope is open) |
| Audit completeness | Every quota change traces to an append-only redemption entry - no silent balance edits |
| Lifecycle honesty | A fully-used grant reads EXHAUSTED; one past its window reads EXPIRED |
4. Personas & Use Cases
| Persona | Goal in this feature |
|---|---|
| Owner / Manager | Configure what is sold as an entitlement - its quota, validity, scope - and read remaining balances |
| Cashier | Sell an entitlement and redeem a customer's balance at the point of sale in a tap |
| Customer | Buy a bundle / pass once and draw it down across many visits, confident the terms won't change |
Core scenario: an owner configures a "10 Coffees" policy on the matching variant - quota 10 cup, no expiry, activates on purchase, scoped to the coffee category via targets. A customer buys it; the system mints a grant with a unique code (like ENT-…), balance 10, status ACTIVE, and freezes the policy + its targets into the grant. On each later visit the cashier redeems one cup: a redemption draws the used counter to 1, 2, … 10; at 10 the grant flips to EXHAUSTED. A mistaken redeem is corrected with a reversal that returns one cup and reopens the balance.
5. User Stories
- As an owner, I declare a sellable variant as an entitlement with a quota and an optional expiry, so I can sell bundles and passes.
- As an owner, I scope an entitlement to the items it covers, so a coffee pass can't be spent on food.
- As an owner, I trust that editing the catalogue later never changes a pass a customer already bought.
- As a cashier, I redeem one use of a customer's balance in a tap, and see what's left.
- As a cashier, I reverse a redemption I made by mistake, and the balance comes back.
- As a customer, I buy once and draw the value down over many visits, and the pass expires only when its window says so.
6. Functional Requirements
| # | Requirement | URD ref |
|---|---|---|
| FR-1 | A policy binds 1:1 to a sellable variant and declares its limit dimensions (count / time-window / metered) | URD-ENT-001..002 |
| FR-2 | A policy carries an optional quota (amount + unit) and an optional validity duration; either axis may be absent | URD-ENT-003 |
| FR-3 | A policy declares an activation mode - on purchase, on first use, or scheduled - governing when validity starts | URD-ENT-004 |
| FR-4 | A policy may require an attached customer, or allow a bearer entitlement | URD-ENT-005 |
| FR-5 | Targets scope a policy to specific items; an empty target set means open access | URD-ENT-006..007 |
| FR-6 | Selling the entitlement variant mints a grant with a unique code, quota balance, and resolved validity window | URD-ENT-008 |
| FR-7 | The grant freezes a snapshot of the policy and its targets at sale time, isolating it from later catalogue edits | URD-ENT-009 |
| FR-8 | A grant tracks quota total vs used (used counter is source of truth; available = total − used) | URD-ENT-010 |
| FR-9 | A grant moves through pending → active → exhausted / expired / suspended / cancelled | URD-ENT-011 |
| FR-10 | A redemption draws the used counter down for a quantity and is captured against its consuming order / item | URD-ENT-012 · URD-ENT-016 |
| FR-11 | A redemption quantity in a different unit from the grant's quota unit is converted via the unit ratio | URD-ENT-013 |
| FR-12 | A redemption validates the redeemed item against the grant's frozen target scope (open when no targets) | URD-ENT-014 |
| FR-13 | A reversal redemption returns quota to the grant; the ledger is append-only - corrections are new entries | URD-ENT-015 |
| FR-14 | Every policy, target, grant, and redemption is confined to the user's own merchant and soft-deleted | URD-ENT-017 |
Full requirement text and acceptance criteria live in the Sale URD - ENT. This PRD references them rather than restating them.
Status: FR-1 through FR-9 and FR-14 are satisfied only at the data-model / CRUD level (the columns, statuses, and snapshot fields exist; entities are confined to the user's merchant and soft-deleted). The behavioural requirements - minting a grant on sale (FR-6, FR-7), drawing down and validating redemptions (FR-10, FR-12), unit conversion (FR-11), reversals (FR-13), and lifecycle transitions (FR-9) - are not yet implemented.
7. Non-Functional Requirements
| Area | Requirement |
|---|---|
| Source of truth | The grant's used counter is authoritative for balance; redemptions are the reconciling audit ledger behind it |
| Immutability | The redemption ledger is append-only; a correction is a reversal entry, never an edit or delete of a prior redeem |
| Snapshot isolation | A grant's terms come from the policy snapshot frozen at sale - never re-read live - so catalogue edits cannot change a sold grant |
| Scope from snapshot | Redemption validates targets from the grant's frozen snapshot, not from a live lookup |
| Tenancy & authz | All operations are confined to the user's own merchant and gated by entitlement permissions |
| Precision | Quota and redemption quantities use decimal precision; cross-unit redemptions convert via the unit ratio |
| i18n | Policy name and description are bilingual (English & Vietnamese) |
8. UX & Flows
The configuration surface lets an owner define a policy on the entitlement variant (quota, validity, activation, scope via targets). The point-of-sale surface sells the entitlement, looks up a customer's grant, shows the remaining balance, redeems a use, and reverses one when needed.
9. Data & Domain
| Entity | Role |
|---|---|
| Policy | The template a merchant configures - bound 1:1 to a sellable variant; carries quota, validity, activation mode, required-customer flag, and limit dimensions |
| Target | A scope binding of a policy to a specific item (variant by default), ordered; empty scope = open access |
| Grant | The sold instance held by a customer - unique code, quota total / used balance, validity window, lifecycle status, and a frozen policy + targets snapshot |
| Redemption | An append-only ledger entry against a grant - a redeem or a reversal, with quantity, unit, and the consuming order / item |
Conceptual only - the full domain model and invariants live in the sale domain model. Cross-area references (variant, order, customer) are tracked by the system, not enforced as hard links.
10. Dependencies & Assumptions
Depends on
- Sale orders (ORD) - a grant is minted off a completed sale of the entitlement variant; redemptions reference the consuming order / item.
- Product (Product) - a policy binds to a sellable variant, and targets scope to catalogue items.
- Units of measure (Inventory) - quota and redemption quantities carry a unit; cross-unit redemptions convert via the unit ratio.
Assumptions
- The merchant configures a policy before selling its variant; selling an unconfigured variant yields no grant.
- A customer is identified when a policy requires one (named entitlement); bearer entitlements may omit the customer.
- The quota counter on the grant and the redemption ledger are kept consistent by the system that applies each redemption.
11. Risks & Open Questions
| Risk / question | Mitigation / status |
|---|---|
| Catalogue edit silently changes a sold pass | Designed mitigation (not yet active) - the grant model carries a policy + targets snapshot to be frozen at sale; the minting logic that populates it is still to be built |
| Balance and ledger could diverge | Designed mitigation (not yet active) - the used counter is intended as the source of truth with redemptions reconciling it via append-only reversals; no runtime applies this yet |
| Redeem against an out-of-scope item | Designed mitigation (not yet active) - redemption is meant to validate the item against the frozen target scope; the validation logic is not yet implemented |
| Customer redeems in a different unit than the quota | Designed mitigation (not yet active) - quantity is intended to convert via the unit ratio before drawing down the counter; conversion is not yet implemented |
| Per-day redemption caps | Out of scope this increment - a per-day cap field is carried on the policy for a future runtime check |
12. Release Plan & Launch Criteria
| Aspect | Plan |
|---|---|
| Phase | P2 - ENT in the URD feature catalog |
| Rollout | All merchants; no feature flag |
| Migration | New tables only (policy, target, grant, redemption); no change to existing order flows |
| Launch criteria | Selling the variant mints a grant with a frozen snapshot; redeem draws the balance down and exhausts at zero; reversal returns quota; out-of-scope redemptions are refused; everything is confined to the user's own merchant |
| Monitoring | Grant balance vs ledger reconciliation, redemption refusal rate by reason (out of scope, exhausted, expired), grants by lifecycle status |
13. FAQ
What can I sell as an entitlement? Anything the customer draws down over time - a drinks bundle, a class pass, a membership window, a block of metered minutes. You bind a policy to the variant and set its quota and validity.
Does editing the policy later change passes already sold? No. Each grant freezes a snapshot of the policy and its scope at sale time and reads its terms from that snapshot, so a catalogue edit never alters a sold grant.
How is the remaining balance tracked? The grant carries a used counter (the source of truth); every use appends a redemption to an audit ledger that reconciles it. Available is the quota total minus what's used.
Can a customer spend a coffee pass on food? Only if the policy is scoped to allow it. A redemption checks the item against the grant's frozen target scope; an empty scope means open access, otherwise out-of-scope items are refused.
What if a cashier redeems by mistake? They record a reversal - an append-only correction that returns the quota. The original redeem is never edited or deleted.
When does a grant expire or exhaust? It reads EXHAUSTED once the used counter reaches the quota total, and EXPIRED once it passes its validity window - the window starting on purchase, first use, or a scheduled date per the policy's activation mode.
References
- URD: Sale - ENT
- Sibling PRDs: Sale order & cart · Loyalty points at order
- Module: Sale - URD
- Developer: @nx/sale · @nx/core