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, andentity_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 ofINSURANCE_POLICY,CONSULTATION,HEALTH_CHECKUP(e.g.entity_types=INSURANCE_POLICY,HEALTH_CHECKUP). An unknown value is a400.benefit_id— a specific benefit.platform_id— the tenant an instance was created under.start_time/end_time— bound results bycreated_at(ISO 8601).sort_on/sort_by— sort (sort_on=created_at,sort_by=asc|desc; defaults to newest first).sort_on=last_modified_atsorts 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’splatform_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.