Per-diem and institutional billing operator playbook

Outcome

ICF / Adult Day / Residential institutional claims roll up into per-diem lines per payer_program_config.institutional_billing_period, with correct accommodation/ancillary split, LOA handling, and admit-date auto-resolution.

Prerequisites

• Familiarity with Institutional context UI for the operator-side data entry.
• claims.read to inspect; claims.update for fixes.

When the per-diem path fires

All of the following must be true:

1. The claim is institutional (claimType = 'I').
2. The caller supplied perDiemOptions to ClaimBuilder.buildClaims (or the institutional claim path is explicitly threading them).
3. The payer-program config row has a non-null institutional_billing_period (migration 096 defaults every row to 'MONTHLY').

Professional claims and unconfigured institutional claims keep the legacy 1-line-per-charge emission.

Billing-period semantics

Value	Bucket key	Typical use
WEEKLY	Monday-anchored YYYY-MM-DD of the service week	Adult Day with weekly claim cycles
MONTHLY	YYYY-MM of the service date	ICF / Residential — common default
SPAN	Constant SPAN	One line per revenue code for the whole stay (short-stay / admit-to-discharge)

Changing a payer-program row from MONTHLY → WEEKLY mid-stay is safe but will fragment the next billing period's claim. Coordinate with the billing ops team before flipping.

Accommodation vs ancillary split

category	Behavior
ACCOMMODATION	Charges accumulate into one claim line per (period, revenue code). accommodation_subtype distinguishes room-and-board, LOA (0180/0183), nursery, subacute (019x), ICU (0200) for downstream reporting.
ANCILLARY	One line per charge. Pharmacy 025x, therapies 042x/043x/044x, BH services 090x.
OTHER / unknown	One line per charge — grouper refuses to silently roll an ambiguous code.

Leave of absence (LOA)

InstitutionalStayStage (S03 scrubbing) validates LOA dates — they must fall inside [admit_date, discharge_date]. Store LOA dates as billing.claim_institutional_code rows with code_type='OCCURRENCE' and code='74'. The S04 grouper drops those service dates from the accommodation roll-up; the 837I emitter auto-merges ctx.loaDates into HI*BH as OCC-74 (dedup on code|date).

Ops expectation: covered_days + non_covered_days = stay_length.

STAY_DAY_MISMATCH on a claim means either:

• An LOA row was missed (expected non-covered days under-counted).
• The stay window on the context row is wrong (admit/discharge auto-resolution issue).

Resolve by reconciling the enrollment record + the LOA source system, then re-scrubbing.

Auto-resolution of admit date

InstitutionalStayStage auto-fills a missing admit_date from the active member.member_program_enrollment row whose window brackets the claim's service_from. The stage stamps the resolved date onto billing.claim_institutional_context.admit_date and emits an INSTITUTIONAL_ADMIT_AUTO_RESOLVED warning.

If auto-resolve fails (no enrollment window matches), the claim rejects with MISSING_ADMIT_DATE. Remediation: add the missing enrollment row or supply the admit date directly on the claim.

Verification queries

-- Every seeded revenue code with its category + subtype.
SELECT code, category, accommodation_subtype, description
  FROM rcm_reference.code_set_revenue
 WHERE is_active = true
 ORDER BY code;

-- A claim's resolved stay context + covered-day math.
SELECT claim_id, admit_date, discharge_date, bill_type,
       drg_code, covered_days, non_covered_days,
       (discharge_date - admit_date + 1) AS stay_days,
       COALESCE(covered_days, 0) + COALESCE(non_covered_days, 0)
         AS reported_days
  FROM billing.claim_institutional_context
 WHERE claim_id = '<claim-id>';

-- LOA dates on the claim (OCCURRENCE/74).
SELECT code_date
  FROM billing.claim_institutional_code
 WHERE claim_id = '<claim-id>'
   AND code_type = 'OCCURRENCE'
   AND code = '74'
 ORDER BY code_date;

Validation

Check	Expected
Reported days = stay_length	Yes
Per-diem lines	One per (period, revenue code) for ACCOMMODATION
LOA OCC-74 rows	Match LOA source system
837I HI*BH segments	OCC-74 emitted for each LOA date

Cross-references

• Institutional context UI for operator data entry.
• Onboarding a payer + program config to set institutional_billing_period.

Next

6.2 — Group session attendance