The benefit entities module is a utilization ledger. One row is recorded every time a user utilizes a benefit — an insurance policy, a consultation, or a health checkup. It answers “which benefits has this user (or every user) utilized, when, and what state is each in?”
How a row is created depends on the benefit type. A type with an owning table (insurance policy, consultation) has its row minted server-side in the same database transaction as the policy / consultation it describes, so a utilization can never be recorded without its owner. A type with no owning table — a health checkup — is the row, so it is created directly through POST /benefit_entities; the other types are refused there.Reads serve admins and app users. An app user sees only its own rows: on the list its user_id filter is overridden, and on a single read another user’s row is indistinguishable from one that does not exist.The status column is mutable, updated through PATCH /benefit_entities/{entity_id}/status.

Row shape

entity_id is polymorphic (it points into two different tables) and so carries no foreign key. When the type has an owning table, integrity is guaranteed at write time because the ledger row is inserted in the owner’s transaction; a type with no owning table has no owner to be orphaned from.

Creating an instance

Most instances are minted server-side, inside the transaction that writes their owning row — an insurance policy or a consultation. A benefit type with no owning table has nothing to be transactional with, so its instance is created directly:
HEALTH_CHECKUP is the only such type today; INSURANCE_POLICY and CONSULTATION are rejected with BEE_1703. Creation is self or admin: an app user may only name itself, an admin may create for anyone, and benefit-provider and platform actors are refused (403) — they mint their instances inside the owning transaction instead. The tenant is taken from the caller’s token, or an admin’s x-platform-id header — never from the body. When Superposition’s benefit.create_side_effects lists CREATE_MRN for the benefit, creation first registers the user’s SELF dependant at the benefit’s provider and writes the MRN row in the same transaction as the instance. A member gender the provider does not accept returns 400 BEE_1708, a provider failure 502 BEE_1709, and a user with no active SELF dependant 400 BEE_1701. See ADR-011.

Status transitions

PATCH /benefit_entities/{entity_id}/status validates the from -> to pair only for benefit types that configure a machine in Superposition (one key per from status, such as benefit.status_transition.created = ["COMPLETED"], resolved on benefit_type, with benefit_id, user_id and benefit_availed_date also in the context for narrower overrides. A pair that is not listed is refused). Every benefit type configures its rows. HEALTH_CHECKUP has no upstream to defer to — the ledger row is its source of truth — so it configures CREATED -> COMPLETED and nothing else. INSURANCE_POLICY and CONSULTATION mirror their own upstream machines, coarsened onto these six statuses. The default for every row is the empty array, so a benefit type whose rows are not configured moves nothing at all. A refused transition returns BEE_1705 (400). Creating an instance is also gated by the benefit’s benefit.* availability rules (the same ones behind GET /benefits/available); a refusal returns BEE_1706 (403). Setting the status a row already holds stays a no-op 200 and never reaches the rule.

History and the mutable status

A utilization is a historical fact: rows are never deleted, and entity_id, entity_type, benefit_id, user_id and created_at are never rewritten. Consultations are recorded at initiation — a consultation that later fails upstream still has a row, because the table records utilization attempts. The one mutable field is status, a benefit-agnostic coarsening of the owner’s own status (insurance PolicyStatus / consultation ConsultationStatus), with last_modified_at alongside it. A freshly minted row starts CREATED. It is written only via PATCH /benefit_entities/{entity_id}/status, which is idempotent (a no-op 200 when already at the target) and otherwise validates the pair against the configured rows described above.

Listing

GET /benefit_entities returns the standard paginated envelope ({ data, total, limit, offset }) and supports:
  • entity_id — narrow to one benefit instance (the utilized policy / consultation id).
  • user_id — scope to a single user (omit to list across all users).
  • entity_types — comma-separated, OR-ed: any of INSURANCE_POLICY, CONSULTATION, HEALTH_CHECKUP (e.g. entity_types=INSURANCE_POLICY,HEALTH_CHECKUP). An unknown value is a 400.
  • benefit_id — a specific benefit.
  • platform_id — the tenant an instance was created under.
  • start_time / end_time — bound results by created_at (ISO 8601).
  • sort_on / sort_by — sort (sort_on=created_at, sort_by=asc|desc; defaults to newest first). sort_on=last_modified_at sorts on the real column — the row is mutable and carries one.
  • limit / offset — pagination (limit capped at 100).

Resolving a benefit instance’s tenant

The ledger is the only place a benefit instance’s platform_id is recorded, so ?entity_id= doubles as a point lookup for “which platform was this policy created under?”. This matters for the enrollment-form preview (POST /users/{user_id}/insurance_policies/preview_enrollment_form), which needs a tenant to decide the fallback address printed on the form when the user has none of their own. App and platform callers carry the tenant in their token; an admin does not, and must name one via the x-platform-id header — which the backend honors only for admin actors. So an admin client resolves it from the ledger first:
Document downloads need no such dance — they are policy-scoped, so the backend resolves the tenant from the ledger itself. The preview is the exception because it is callable before a policy exists (the app’s pre-purchase flow), where there is no ledger row to read.