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
BILLING_NPI_TYPE_MISMATCH	ERROR	entity_type disagrees with payer_program_config.billing_npi_type for the claim's payer + service_from.
PAYER_PROGRAM_CONFIG_MISSING	WARN	No active PPC row — claim is not blocked, just not gated.
BILLING_NPI_TYPE_AMBIGUOUS	WARN	Multiple active PPC rows for the same payer disagree. Resolve by picking one and UPSERTing.
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.payer_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