Manage payers, programs & contracts

Outcome

A payer your organization bills is registered in the platform with all the context the rest of the workflows need: contracts, programs (Medicaid waiver, commercial product), aliases the EDI files arrive under, and program-level configuration like timely-filing windows and authorization workflow.

Prerequisites

Scope	What it lets you do
billing.payer.read	View list / detail / contracts
billing.payer.write	Add / edit payers, programs, aliases, contracts

Open Configuration → Payers from the left navigation. The list shows every payer your tenant has enrolled, by display name, with quick filters by line of business (Medicaid, Commercial, Medicare).

What lives where

• Payer is the legal entity. Carries the display name and primary EDI ID.
• Alias is any other identifier you might receive on inbound files (an 837 ID, a clearinghouse remittance ID, a state plan code). Aliases are how the platform recognizes inbound traffic for this payer.
• Program is a specific product (a Medicaid waiver, a commercial PPO). Most billing rules attach to the program, not the payer.
• Contract is the negotiated agreement that drives rates and certain filing rules.
• Program config holds per-program operational knobs: timely-filing window in days, authorization workflow (AUTOMATIC_278, MANUAL_PENDING, NONE), and submission routing.

Steps

1. Pick Configuration → Payers to land on /admin/payers. Click + New payer to register a payer the platform does not yet know about, or click an existing row to open its detail.

2. The detail page has five tabs: Overview, Programs, Aliases, Contracts, History.

   Tab	What you do here
   Overview	Display name, line of business, primary EDI ID, status.
   Programs	Add a program; edit its program config (filing window, auth workflow).
   Aliases	Add IDs you receive this payer under on inbound files.
   Contracts	Effective dates, rate-source link, fee schedule attachment.
   History	Audit trail of edits.

3. Add a program under the Programs tab. The dialog asks for:

   • Program name — free-text display.
   • Program code — your internal code; appears on charges and reports.
   • Line of business — Medicaid / Commercial / Medicare.
   • Authorization workflow — controls how authorizations behave for this program. AUTOMATIC_278 runs the standard X12 278 flow; MANUAL_PENDING parks new auth requests in a manual queue (used for payers who do not accept electronic auth submission); NONE skips authorizations entirely.
   • Timely filing days — how many days from date-of-service the platform warns about, then blocks, late submissions.
   • Institutional billing period — DAILY, WEEKLY, MONTHLY, SPAN. Drives per-diem grouping.

4. Add an alias under the Aliases tab. Aliases come in three flavors:

   Source	Example
   EDI submission ID	The ISA08 your 837 must carry to this payer.
   EDI remittance ID	The ID this payer puts on the inbound 835.
   External plan code	A state plan code or similar that appears on member files.

   Aliases can be deactivated (preferred) but never deleted, so the trail of which ID was active when you posted any given remittance stays intact.

5. Add a contract under the Contracts tab. Contracts hold:

   • An effective from / to window.
   • A rate source — usually a fee schedule (see Manage fee schedules).
   • A filing window override — if the contract negotiates a different timely-filing window than the program default.
   • An authorization carve-out — services that bypass the program's auth workflow under this contract.

Validation

Check	Expected
New payer appears on /admin/payers	Yes, immediately.
Program config saved	The Programs tab reflects the change; History tab carries an audit row.
EDI submission ID alias added	When you submit an 837 to this payer, the file carries the new ID.
Contract effective	New charges priced after the effective date use the contract's fee schedule.

Troubleshooting

Symptom	Cause	Fix
Save returns 409 Conflict	Another active alias already owns this EDI ID	Deactivate the prior alias first.
Charges priced at $0	No active fee schedule on the contract	Attach a fee schedule (see Manage fee schedules).
Auth requests sit in DRAFT forever	Program's authorizationWorkflow is NONE or MANUAL_PENDING	Either submit manually from the auth detail page, or change the program config to AUTOMATIC_278.
Inbound 835 fails to match a payer	The remittance ID on the 835 has no alias	Add the ID under Aliases; the next 835 will match.

Next

5.2 — Manage fee schedules