Commercial billing-NPI and filing windows

Outcome

A billing entity is correctly typed (INDIVIDUAL / GROUP / FACILITY), filing windows reflect commercial payer SLAs, and the BillingNpiStage gate rejects mismatches before submission.

Prerequisites

• config.update for tenant updates.
• PLATFORM_ADMIN for master payer seeds.

Classify a billing entity

identity.billing_entity.entity_type is INDIVIDUAL | GROUP | FACILITY, default GROUP. Set INDIVIDUAL or FACILITY explicitly when onboarding a sole-proprietor provider or an institutional billing entity.

UPDATE identity.billing_entity
   SET entity_type = 'INDIVIDUAL'
 WHERE billing_entity_id = '<id>';

The CHECK constraint rejects any value outside the enum.

How the BillingNpiStage gate works

The stage runs globally after GroupBillingStage and before the state phase. No config toggle is required.

Code	Severity	Meaning
PROGRAM_CONFIG_MISSING	ERROR	The claim has no program, no program setting is in force on service_from (neither the payer's own nor the program's), or the setting does not accept claims. Add or extend the setting under Configuration → Programs. It was the warning PAYER_PROGRAM_CONFIG_MISSING before #5990, when the claim went out ungated.
BILLING_NPI_TYPE_MISMATCH	ERROR	entity_type disagrees with program_config.billing_npi_type of the setting in force for the claim's program and payer on service_from.
BILLING_ENTITY_MISSING / BILLING_ENTITY_TYPE_UNSET	WARN	Defensive branches; the upstream field-validation stage covers missing-entity cases first.

Seeded commercial payers

Master migration 043 ships deterministic payer stubs so TimelyFilingTracker alerts on real commercial windows:

Payer	Prof TFD	Inst TFD
UnitedHealthcare	90	90
Anthem BCBS	120	120
Aetna	120	180
Cigna	90	180
Humana	180	180

These rows have stable canonical payer_id UUIDs — never duplicate them with fresh UUIDs.

Override a filing window per tenant contract

The seeded rows are payer-wide defaults. If a tenant's commercial contract carries a different filing window (e.g., UHC's behavioural-health master service agreement extends to 180 days), the right place is a tenant config.program_config row.

TimelyFilingTracker currently prefers the master payer_submission_capability row; a follow-up hook will read tenant overrides directly. Until then, update master timely_filing_days only if the capability is truly different by contract — otherwise let the default stand.

Validation

Check	Expected
billing_entity.entity_type for sole-proprietor	INDIVIDUAL
BillingNpiStage warning rate	Low; resolve MISSING and AMBIGUOUS warnings
Filing-window alerts	Track real per-payer SLAs

Troubleshooting

Symptom	Cause	Fix
BILLING_NPI_TYPE_MISMATCH blocking valid claims	entity_type wrong on billing_entity	Update via SQL above.
BILLING_NPI_TYPE_AMBIGUOUS warns repeatedly	Two active PPC rows disagree	Pick the right one, UPSERT to align.
Commercial timely-filing alerts not firing	Master payer not seeded	Run migration 043 fan-out.

Cross-references

• Onboarding a payer + program config for PPC row management.
• Commercial payer onboarding for the bulk seed.
• Timely filing alerts to surface filing-window risk.

Next

4.3 — Payer-scoped modifier overrides