2.6 Payers, contracts, fee schedules, and program configs

Outcome

Every payer the customer bills is linked to the tenant with a contract, a fee schedule, filing rules, and (where applicable) a program config (auth workflow, EOB posting style).

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 config (billing.payer_program_config): auth workflow, EOB posting semantics, billing-entity preference per payer + program.

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 — UI-02 runbook chapter for the import format.

6. Add a program config (drives auth workflow + EOB posting style)

   Admin → Payers → <payer> → Programs → Add program

   Field	Example
   Program code	OH_MEDICAID_FFS
   Display label	OH Medicaid FFS
   Auth workflow	MANUAL_PENDING (manual entry) or EDI_278 (real-time)
   Institutional billing period	n/a for outpatient; WEEKLY/MONTHLY/SPAN for institutional
   EOB posting style	MEDICAID_DETAIL or COMMERCIAL_CONTRACT
   Default billing entity	(link from 2.5)

   The choice between MEDICAID_DETAIL and COMMERCIAL_CONTRACT affects how Receivables splits PR vs CO adjustments — see the runbook chapter on Commercial EOB Posting.

7. Repeat steps 1–6 for every payer in the panel

   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 + program config in one transaction. Edit afterward in the UI.

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
billing.payer_program_config rows	one per (payer, program) the customer bills

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.

Next

2.7 — Rules and modifiers