> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Practice Management Contracts

> View payer contracts and contracted rates, view capitation contract details, and model revenue scenarios with the contract modeling wizard.

The Contracts page (`/pm/contracts`) lists all payer contracts recorded for your organization, sorted soonest-expiring first.

## Overview

The Contracts page loads all payer contracts for the current organization from the `pm_payer_contracts` table, joined to `pm_payers` for the payer name. Records marked as deleted (`deleted_at` not null) are excluded. The list defaults to ascending sort by `termination_date` so the soonest-expiring contracts appear first. Users with `pm.contracts.manage` permission see a **New Contract** button that opens a creation dialog. Each row in the table links to the contract detail page at `/pm/contracts/:id`.

## Who it's for

Requires permission `pm.contracts.view` (`PM_PERMISSIONS.CONTRACTS_VIEW`).

Users with `pm.contracts.manage` can also create new contracts via the **New Contract** dialog.

## Before you start

* You must hold the `pm.contracts.view` permission.
* At least one payer must exist in the system before a contract can be associated to it.

## Steps

<Steps>
  <Step title="Open the Contracts page">
    Navigate to `/pm/contracts`. The table loads automatically and shows all non-deleted contracts for your organization.
  </Step>

  <Step title="Filter the list">
    Use the **All Payers** dropdown to narrow to a specific payer, and the **All Statuses** dropdown to filter by status (`active`, `expired`, `terminated`, or `pending`). Both filters can be applied simultaneously. When active filters return no rows, the table displays "No contracts match the filters."
  </Step>

  <Step title="Open a contract">
    Click the payer name link in the **Payer** column to open the contract detail page at `/pm/contracts/:id`.
  </Step>

  <Step title="Create a contract (manage permission required)">
    Click **New Contract** in the page header. The `PayerContractFormDialog` opens in `create` mode. Complete the form and save.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Contract statuses">
    The list recognizes four statuses: `active` (shown as a filled badge), `pending` (outline badge), `expired` and `terminated` (both shown as secondary/muted badge). The UI does not visually distinguish between `expired` and `terminated`.
  </Accordion>

  <Accordion title="Auto-Renew column">
    The **Auto-Renew** column (hidden on mobile) shows `Yes` or `No` based on the `auto_renew` field on the contract record.
  </Accordion>

  <Accordion title="Empty state">
    When no contracts exist yet, the page shows: "No contracts yet — Create a payer contract to track contracted rates and detect underpayments." The filter dropdowns are not rendered until at least one contract exists.
  </Accordion>
</AccordionGroup>

## Viewing a capitation contract

The Contract Details screen displays a single capitation contract record at route `/pm/capitation/:id` (permission: `pm.capitation.view`). The component is `CapitationContractPage`. It displays the contract fields and PMPM revenue reconciliation data.

1. Navigate from the Capitation hub (`/pm/capitation`) and select a contract to open its detail page.
2. Review the contract fields and PMPM reconciliation data displayed by the component.

## Modeling a contract scenario

The Contract Modeling Simulation Wizard at `/pm/contracts/modeling/new` guides users through a five-step process to model and version revenue scenarios for payer contracts. Requires permission `pm.contracts.view`.

`ContractModelingWizardPage` renders `WizardShell` with five steps driven by `useContractModelingWizard`. On success, the user is redirected to `/pm/contracts`.

**Before you start:** an existing payer contract must be present at `/pm/contracts` to use as a baseline. Ensure volume projections data is available for the scenario period.

<Steps>
  <Step title="Open the wizard">
    Navigate to **Practice Management → Contracts → Modeling → New**, or go to `/pm/contracts/modeling/new`.
  </Step>

  <Step title="Select a baseline contract and timeframe">
    On the **Baseline Selection** step, choose an existing payer contract and define the modeling period.
  </Step>

  <Step title="Enter volume assumptions">
    On the **Volume Assumptions** step, provide service volume projections for the scenario.
  </Step>

  <Step title="Adjust rates">
    On the **Rate Adjustments** step, apply code-level rate changes to model a proposed contract scenario.
  </Step>

  <Step title="Review forecast output">
    On the **Forecast Output** step, review computed revenue metrics. If inputs changed, click **Recompute** to refresh the forecast.
  </Step>

  <Step title="Save and version the scenario">
    On the **Review & Submit** step, confirm all inputs and submit. The scenario is versioned and you are redirected to `/pm/contracts`.
  </Step>
</Steps>

**Stale forecast** — the forecast is marked stale when volume or rate inputs change; a recompute is required before submission.

**Scenario versioning** — each submission creates a versioned snapshot; existing contracts are not modified.

## Detail view

The Contract screen displays a single payer contract with its contracted rate table at route `/pm/contracts/:id`.

### Overview

The page loads a contract via `usePayerContractDetail`. It displays a Contract Details card showing status badge, effective date, termination date, and auto-renew indicator. A Contracted Rates card lists rate entries in a table with CPT code, modifiers, rate amount, rate type, effective date, and end date. Users with `pm.contracts.manage` can add rates (via `ContractedRateFormDialog`), edit existing rates, delete rates, edit the contract header (via `PayerContractFormDialog`), and copy the contract for renewal (via `ContractRenewalDialog`). Rate deletion calls `useDeleteContractedRate`.

### Who it's for

Requires permission `PM_PERMISSIONS.CONTRACTS_VIEW` (enforced via `RequirePermission` in the route definition). Rate and contract management requires `pm.contracts.manage`.

### Before you start

* You need `pm.contracts.view` to access this page.
* Navigate here from the Contracts list (`/pm/contracts`).

### Steps

<Steps>
  <Step title="Open a contract">
    Navigate from the Contracts list (`/pm/contracts`) and click a row to open the contract detail page.
  </Step>

  <Step title="Review contract details">
    The Contract Details card shows status, effective date, termination date, and auto-renew setting.
  </Step>

  <Step title="Review contracted rates">
    The Contracted Rates table lists all rates with CPT code, modifiers, rate, type, effective dates, and end dates.
  </Step>

  <Step title="Add a rate (pm.contracts.manage)">
    Click **Add Rate** to open the ContractedRateFormDialog and enter a new rate entry.
  </Step>

  <Step title="Edit or delete a rate (pm.contracts.manage)">
    Use the edit (pencil) or delete (trash) icons on any rate row to modify or remove it.
  </Step>

  <Step title="Copy as new / renew">
    Click **Copy as new** to open the ContractRenewalDialog and create a duplicate contract for renewal.
  </Step>
</Steps>

### Key concepts

| Term                                  | Meaning in code                                                                        |
| ------------------------------------- | -------------------------------------------------------------------------------------- |
| `contract_number`                     | Identifier for the payer contract                                                      |
| `payer_name`                          | Name of the payer; sourced from the contract record                                    |
| `auto_renew`                          | Boolean flag on the contract                                                           |
| `rate_type`                           | Category of the contracted rate (values displayed with underscores replaced by spaces) |
| `ContractStatus`                      | Status of the contract: `active`, `pending`, or other                                  |
| `effective_date` / `termination_date` | Contract validity period                                                               |

## Related

<Columns cols={2}>
  <Card title="Practice Management" icon="briefcase" href="/pm/overview">
    Overview of the Practice Management core.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/pm.tsx
  * src/cores/pm/pages/PayerContractsListPage.tsx
  * src/cores/pm/hooks/usePayerContractList.ts
  * src/platform/permissions/constants.ts
  * src/cores/pm/pages/capitation/CapitationContractPage.tsx
  * src/cores/pm/pages/ContractModelingWizardPage.tsx
  * src/cores/pm/hooks/useContractModelingWizard.ts
  * src/cores/pm/pages/PayerContractDetailPage.tsx
  * src/cores/pm/hooks/usePayerContractDetail.ts
  * src/cores/pm/hooks/useContractedRateMutation.ts
</Accordion>