---
id: SVC-COM-ORD-entitlements
title: Entitlements Service Module
product_area: commerce
module: orders
repository: services-commerce
source_module: modules/entitlements
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b
owns:
  - DOM-COM-ORD-004
does_not_own:
  - Fulfilment retains grant-obligation dispatch.
  - Platform retains decisions that consult active-rights facts.
  - Consumers retain the business records associated with their benefit use.
operations:
  - operation_id: getEntitlementsHealth
    intent: Expose entitlements runtime health and build information without customer records.
    access: public
    permission: 'none: public health route'
    realises: []
    published_to_submissions: 'not published: runtime status is outside submission processing.'
  - operation_id: listEntitlements
    intent: 'Retrieve grants by holder or order, restricting portal results to the linked contact.'
    access: portal
    permission: commerce.entitlements.read
    realises:
      - CAP-COM-ORD-013
    published_to_submissions: 'not published: grant retrieval is distinct from the database consumption boundary.'
  - operation_id: getEntitlement
    intent: Retrieve a grant and its consumption records.
    access: portal
    permission: commerce.entitlements.read
    realises:
      - CAP-COM-ORD-013
    published_to_submissions: 'not published: retrieval has no submission-stage binding.'
  - operation_id: restoreEntitlementUse
    intent: 'Restore consumed allowance with a reasoned, keyed staff intervention.'
    access: console
    permission: commerce.entitlements.restore
    realises:
      - CAP-COM-ORD-013
    published_to_submissions: 'not published: administrative correction has no submission-stage binding.'
  - operation_id: grantEntitlement
    intent: 'Create a benefit manually with a reasoned, keyed staff intervention.'
    access: console
    permission: commerce.entitlements.grant
    realises:
      - CAP-COM-ORD-013
    published_to_submissions: 'not published: administrative correction has no submission-stage binding.'
  - operation_id: revokeEntitlement
    intent: 'End grant availability with a reasoned, keyed staff intervention while preserving past uses.'
    access: console
    permission: commerce.entitlements.revoke
    realises:
      - CAP-COM-ORD-013
    published_to_submissions: 'not published: administrative correction has no submission-stage binding.'
  - operation_id: consume_entitlement
    intent: Consume benefits atomically with the caller's database work using a repeatable consumer reference.
    access: internal
    permission: 'database: EXECUTE granted to the rhythm_commerce_consumer role only'
    realises:
      - CAP-COM-ORD-013
    published_to_submissions: >-
      not published as a Submissions operation: this database function can consume existing requirement rights
      within a caller transaction.
events:
  - name: 'order history events (entitlements granted, revoked, reinstated, use restored)'
    direction: produced
    when: 'Purchased-right creation, revocation and restoration append order history.'
    payload_summary: 'Local history identifies the purchase, affected rights and intervention reason.'
  - name: commerce.intervention audit event
    direction: produced
    when: 'Committed staff restoration, discretionary grants and revocation emit an intervention audit request.'
    payload_summary: >-
      Audit requests carry subject, attributed action and local intervention identity through the default
      stand-in.
jobs:
  - name: entitlement expiry pass
    schedule: every minute inside the checkout sweeper function
    purpose: Mark active rights expired after their validity window ends.
integrations:
  - system: Platform eligibility
    direction: outbound
    contract: The Platform reader role can query current rights through a restricted read-only view.
  - system: 'Consuming applications (downloads, Submissions)'
    direction: inbound
    contract: Consumers draw allowances through the shared transactional consumption function.
consistency:
  - rule: 'Purchased grants are unique by line and kind, with history sharing their commit.'
    kind: transactional
    compensation: Failed grant persistence rolls back its associated history.
  - rule: Consumption replays its reference and shares the consumer transaction.
    kind: transactional
    compensation: Consumer rollback also rolls back allowance consumption.
  - rule: 'Scheduled marking can lag validity end, which consumption enforces directly.'
    kind: eventual
    compensation: The next eligible pass records elapsed grants.
evidence:
  - >-
    services-commerce at c8b66a98: modules/entitlements/aws/api/entitlements.routes.ts (route declarations),
    entitlements.schemas.ts; aws/entitlements.module.ts; services/**; db/*.table.ts;
    services-commerce:db/migrations/20261018130023_entitlements.sql; aws/commerce.service.ts
    (EntitlementRoutePermissions).
controls: [TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-AVL-002, TC-AVL-003, TC-MON-001, TC-MON-003, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-005, TC-PRV-001, TC-PRV-002]
---

# Entitlements Service Module

## What This Service Is For

Entitlements records purchased benefits, exposes controlled consumption and supports accountable staff correction. Rights can be granted, revoked or have a consumed use restored.

## Boundary

The module owns grants and use records. Fulfilment dispatches its internal grant handler, eligibility reads a view, and consuming applications call the database consumption function. Frozen purchase details determine what a product grants.

## Operations in Words

Readers retrieve grants and consumption subject to holder authority. Staff interventions require permission, explanation and request replay. Consumers draw benefits through the database boundary rather than an HTTP write. No operation is published as a Submissions contract.

## Events and Jobs

Purchased-grant changes append local order history, and interventions attempt an audit message after commit. Validity expiry runs within the shared minute schedule.

## Consistency Guarantees

Grant uniqueness and consumption references protect repeated requests. Consumption commits with the consumer's work and checks validity directly, so delayed expiry marking does not extend availability. Durable intervention audit delivery remains absent.