2.6 Payers, contracts, fee schedules, and program settings

Outcome

Every program the customer bills has a program setting in force (auth workflow, filing window, submission), with payer-specific settings only where a payer differs, and every payer the customer bills has a contract and a fee schedule.

Prerequisites

• 2.5 Org and facilities complete.

Building blocks

The payer registry lives in master and is shared across tenants. Each tenant then overlays:

• A contract (billing.payer_contract): the rate book this customer negotiated.
• A fee schedule (billing.fee_schedule + billing.fee_schedule_entry): the per-procedure-code dollar amounts.
• A program setting (config.program_config): per program, with the payer optional — accepts claims, auth workflow, filing window, billing NPI type. The row with no payer applies to every payer of the program.
• Code overrides (optional): the customer's own rates over MedSuite's program rules (rcm_master.program_rule), per program and state, for every payer or one payer.

Steps

1. Verify the payer exists in master

   Admin → Payers → search "Anthem Ohio".

   If missing, create it (platform-level, affects every tenant):

   Admin → Payers → Add payer

   Field	Value
   Name	Anthem Blue Cross Blue Shield Ohio
   Short name	Anthem OH
   Payer code	ANT-OH
   Payer type	COMMERCIAL or MEDICAID_FFS or MEDICAID_MCO
   Electronic payer ID	OH054
   State	OH

2. Add submission capabilities (per transaction type the customer will exchange)

   Admin → Payers → <payer> → Capabilities → Add

   Field	Example
   Tx type	837P
   Filing deadline (days)	90
   Electronic supported	yes
   Companion guide	link to PDF

3. Impersonate the tenant to add per-tenant overlay rows.

   Admin → Tenants → Acme → Switch to tenant. The remaining steps happen in the tenant-side admin UI.

4. Add a payer contract (tenant-side)

   Admin → Payers → <payer> → Contracts → Add contract

   Field	Value
   Effective from	2026-01-01
   Effective to	(open)
   Contract NPI (group)	matches the billing entity from 2.5
   Notes	"Renewal expected 2027-01"

5. Build a fee schedule

   Admin → Fee schedules → New fee schedule

   Field	Value
   Name	Anthem OH 2026
   Contract	(link to step 4)
   Currency	USD

   Then either:

   • Manual entry: add procedure codes one at a time.
   • CSV import: drag-drop a CSV with columns code, modifier, amount, effective_from. The importer dry-runs first and shows you a diff before commit.

   See Fee schedules for the import format.

6. Add a program setting for every program the customer bills (drives claim acceptance, auth workflow, filing window, billing NPI type, institutional billing period)

   Configuration → Programs → New program setting (/admin/programs)

   Field	Example
   Payer (optional)	leave empty — the program setting every payer follows
   Program	picked by name from the master program list (rcm_master.program)
   Effective from	the customer's first date of service (earlier to back-bill; needs a reason)
   Accepts claims	on
   Claim type / Submission method / Billing NPI type	P / EDI / GROUP
   Auth workflow	EDI_278, PORTAL (portal URL required) or MANUAL
   Timely filing days	blank falls back to the payer's submission TFD
   Institutional billing period	n/a for outpatient; WEEKLY/MONTHLY/SPAN for institutional

   A claim whose program has no setting in force on its first date of service, or whose setting does not accept claims, is blocked at scrub with PROGRAM_CONFIG_MISSING (#5990). There are no payer program enrollments any more: MedSuite's rates and code rules are chosen by the program, the facility's state and the payer, so the facility addresses from 2.5 must carry a state.

   Only where one payer bills the program differently, add a payer-specific setting: Add setting on the program's group, or the payer → Programs tab → New payer-specific setting. It replaces the program setting for that payer, so fill in every field. The payer's Programs tab also lists, read only, the MedSuite payer exceptions (master rates for that payer).

   Only where the customer's rates differ from MedSuite's, open the program and state under Configuration → Code Overrides and replace, exclude or add codes for every payer of the program or for one payer.

7. Repeat steps 1–5 for every payer in the panel (step 6 is once per program)

   For commercial payers (UHC, Anthem, Aetna, Cigna, Humana), there's a one-shot helper:

   pnpm tsx scripts/seed-commercial-payer.ts --tenant acme --payer UHC

   This seeds a contract + 90-day TFD fee schedule template + 3 most-common entries + a payer-specific setting in one transaction. Edit afterward in the UI. It does not add the program setting other payers follow — step 6 still applies.

Validation

Check	Expected
billing.payer_contract rows for tenant	one per payer in panel
billing.fee_schedule rows	one per active contract
billing.fee_schedule_entry row count	matches imported CSV
config.program_config rows with payer_id NULL	one in force per program the customer bills
Payer-specific config.program_config rows	only where a payer differs
Getting Started B5 / B6	no program on active coverage without a setting

Troubleshooting

Symptom	Likely cause	Fix
Importing CSV: "duplicate (code, modifier)"	Source CSV has dupes	Dedupe in spreadsheet, retry.
Cannot pick contract NPI	Billing entity not linked to a facility yet	Complete 2.5 first.
Auth workflow EDI_278 not selectable	Capability for 278 not configured for this payer	Add the 278 capability in step 2.
Claims blocked with PROGRAM_CONFIG_MISSING	No program setting in force on the first date of service, or it does not accept claims	Add the program setting (step 6) or move its effective from earlier.
Code Overrides lists only National rows	No facility has a state	Add the state to each facility (2.5).

Next

2.7 — Rules and modifiers