--- id: CON-COM-ORD-004 name: Entitlement feature: FEAT-COM-ORD-05 product_area: commerce module: orders revision: 1 status: draft product_intent: proposed implementation_evidence: observed source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- An entitlement records a contact or organization’s right to use a purchased or manually granted benefit, subject to its quantity, timing and status. owned_by: MOD-COM-ORD synonyms: - grant - right not_to_be_confused_with: - Membership — Membership’s own record - Eligibility rule — a qualifying rule that may consult the right - Permission — authority for staff actions facets: - name: Benefit category meaning: 'The download, registration, submission or access kind of the right.' used_for: Identify the benefit available to the holder. - name: Beneficiary meaning: 'The recipient named on a purchased line, or the buyer when no recipient is named.' used_for: Associate the right with its contact or organization. - name: Allowance and use history meaning: 'A finite number of uses and their numbered records, or an unlimited allowance when quantity is absent.' used_for: Track benefit consumption. - name: Availability dates meaning: 'The start and end of availability, with no expiry when an end is absent.' used_for: Apply time-limited access. - name: Grant origin meaning: A delivered purchase or a staff-created grant. used_for: Explain how the holder obtained the right. - name: Service interventions meaning: 'Restoration, manual granting and revocation with an actor and reason.' used_for: Support accountable customer service. relationships: - to: CON-COM-ORD-002 statement: >- A purchased grant links to its originating order line; cancellation stops further use while retaining usage history. provenance: test source: >- services-commerce:modules/entitlements/tests/e2e/entitlements.e2e.spec.js#revokes the line’s grant with the reason, refuses the download 409 entitlement_not_active, and writes the history - to: CON-COM-ORD-003 statement: The application declares the purchased benefit and Commerce creates the entitlement. provenance: observed source: 'services-commerce:modules/entitlements/services/register/grant-specification.ts' lifecycle: - state: Active meaning: The grant can be used within its dates and allowance. how_it_changes: Delivery or a manual grant creates the active right. - state: Revoked meaning: Availability has been stopped while previous uses remain recorded. how_it_changes: 'Cancellation, enforcement or staff revocation records the reason.' - state: Expired meaning: The availability window has ended. how_it_changes: The minute sweep updates expiry status; draw checks already reject expired rights. acted_on_by: - CAP-COM-ORD-012 - CAP-COM-ORD-013 - CAP-COM-ORD-014 visible_to: - ACT-COM-016 - ACT-COM-015 - ACT-COM-017 evidence: - 'Examined reference: services-commerce:modules/entitlements/services/register/grant-specification.ts' - >- Examined reference: services-commerce:modules/entitlements/tests/e2e/entitlements.e2e.spec.js#revokes the line’s grant with the reason, refuses the download 409 entitlement_not_active, and writes the history supersedes: [] --- # Entitlement ## What It Is An entitlement makes a benefit available to its holder. It can represent a download allowance, an included registration, a submission requirement or access. The record answers who has the right, what kind of right it is and whether it can be used now. Where the benefit has a finite allowance, it also connects the remaining quantity to the uses already recorded. The right may come from delivery of a purchased line or from a staff grant. Keeping that origin visible helps staff explain why the holder has the benefit. A purchased grant connects the right to the sale that produced it, while a manual grant has its own staff action and reason. These origins serve different customer-service needs without requiring separate definitions of the right itself. ## What It Is Not A membership is a record owned by the Membership application. An eligibility rule can consult an entitlement when deciding whether someone qualifies for an action. A staff permission controls what a staff member can do in the product. An entitlement instead describes the benefit held by the contact or organization; possessing one does not make its holder an administrator. ## How It Is Used Applications use entitlement operations when a holder consumes a benefit. Staff read the grant and its usage history to answer questions or make an authorized correction. A repeated request needs to connect to the existing use rather than silently consume another unit. The entitlement capability describes the checks on quantity, time and status and the evidence for retry behavior. Customer service also needs to explain the end of a right. Expiry concerns the time window, while revocation concerns a decision to stop availability. Previously recorded use remains part of the history. Cancellation of a purchased line can revoke its associated grants, including active grants whose allowance has already been consumed; the retained usage record explains what occurred before revocation. ## Its Facets **Benefit category.** The download, registration, submission or access kind of the right. Identify the benefit available to the holder. **Beneficiary.** The recipient named on a purchased line, or the buyer when no recipient is named. Associate the right with its contact or organization. **Allowance and use history.** A finite number of uses and their numbered records, or an unlimited allowance when quantity is absent. Track benefit consumption. **Availability dates.** The start and end of availability, with no expiry when an end is absent. Apply time-limited access. **Grant origin.** A delivered purchase or a staff-created grant. Explain how the holder obtained the right. **Service interventions.** Restoration, manual granting and revocation with an actor and reason. Support accountable customer service. ## How It Relates A purchased grant links to its originating order line; cancellation stops further use while retaining usage history. The application declares the purchased benefit and Commerce creates the entitlement. The capability references identify where the detailed behavior is defined; this concept supplies the vocabulary used across those outcomes. ## What It Could Become The product should decide how holders and staff see remaining allowances and intervention reasons. The product should resolve the proposed self-service experience separately from the implemented entitlement engine. Before adding management screens, the design should establish which staff actions need a reason, how restoration is explained and how a revoked or expired benefit appears to its holder.