Last Updated: 2026-02-27
Status: ✅ Complete — 2026-02-28
Spec: PM-23 Contract & Fee Schedule Management
Constitution Reference: Section 1.2 (Core Independence), Section 1.3 (Integration Patterns)
Overview
PM-23 adds payer contract and contracted rate management: contracts with terms and effective/termination dates, rate schedules per contract (CPT, modifiers, rate, rate_type), underpayment detection (ERA paid amount vs contracted rate), contract expiration alerts, and rate comparison reporting. It integrates with PM-07 (fee schedules), PM-08 (claim expected amounts), PM-09 (payment posting/variance), and PM-11 (analytics).Integration Points (from spec)
Data Source Tables (PM-23)
Platform Layer Usage
- PM-07: May consume contracted rates for fee schedule display or expected amount; link optional (contracted vs org-defined fee schedule).
- PM-08: When generating claim expected amount, look up contracted rate by payer + CPT + date; fallback to org fee schedule when no contract.
- PM-09: On payment posting, look up contracted rate for claim payer + line CPT; if paid_amount < rate, set underpayment flag (storage location TBD in implementation).
- PM-11: Read pm_payer_contracts and pm_contracted_rates for contract analytics, rate comparison across payers, underpayment reports.
- Permissions:
pm.contracts.view,pm.contracts.managegate UI; RLS enforces tenant isolation.
Event / API Contracts
- Same-core data only. No new event or API contracts; PM-07, PM-08, PM-09, PM-11 access tables via direct (RLS-scoped) queries or existing platform patterns.