> ## 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 Payment Plans

> Create and manage patient installment payment arrangements, including plan status, frequency, amounts, and per-plan detail view.

The Payment Plans page (`/pm/payment-plans`) lists all active patient payment arrangements for the organization and allows authorized users to create new plans.

## Overview

The page renders a card titled "Active Plans" containing a table of payment plan records from `pm_payment_plans`. Each row links to the plan detail page at `/pm/payment-plans/:planId`. The table columns are: Start Date, Total (amount), Installment (per-period amount), Frequency, and Status. Status values are rendered as badges. Users with the `pm.payment_plans.create` permission see a "New Payment Plan" button that opens the `PaymentPlanFormDialog`.

Note: A separate payment plan detail page exists at `/pm/patient-payment-plans/:planId` for the PM-45 collections workflow, which includes installment timeline and action controls.

## Who it's for

Requires permission: `pm.payment_plans.view` (inline string guard in component and route)

## Before you start

* Your account must have the `pm.payment_plans.view` permission.
* To create a new plan, you additionally need `pm.payment_plans.create`.
* Patient records must exist in the system before a payment plan can be associated with a patient.

## Steps

<Steps>
  <Step title="Navigate to Payment Plans">
    Go to `/pm/payment-plans`. The Active Plans card loads all non-deleted plans for your organization, sorted by creation date descending.
  </Step>

  <Step title="Open a plan">
    Click a plan's Start Date link to open the detail page at `/pm/payment-plans/:planId`.
  </Step>

  <Step title="Create a new plan (requires pm.payment_plans.create)">
    Click "New Payment Plan" in the page header. Complete the form in the `PaymentPlanFormDialog` and submit.
  </Step>

  <Step title="Retry on error">
    If the plans fail to load, an error message and a "Retry" button appear inside the card. Click "Retry" to reload the page.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Payment plan status">
    Each plan has a status badge. The status values and their display labels are defined in `PAYMENT_PLAN_STATUS_LABELS` (`src/cores/pm/types/statement-billing.ts`).
  </Accordion>

  <Accordion title="Payment frequency">
    The Frequency column displays human-readable labels for each installment cadence, sourced from `PAYMENT_PLAN_FREQUENCY_LABELS`.
  </Accordion>

  <Accordion title="Empty state">
    When no plans exist, the page shows: "No payment plans — Create a plan to set up installment payments."
  </Accordion>
</AccordionGroup>

## Viewing a payment plan

The Payment Plan Details page displays a single patient payment plan record, including financial summary and installment schedule at route `/pm/payment-plans/:planId` (permission: `pm.payment_plans.view`).

`PaymentPlanDetailPage` loads a plan via `usePaymentPlanDetail` keyed by `planId`. It displays a three-column summary grid with Total Amount, installment frequency, and status badge (using `PAYMENT_PLAN_STATUS_VARIANT` and `PAYMENT_PLAN_STATUS_LABELS`). The start date is shown in the page header. Breadcrumbs link back to `/pm/payment-plans`.

1. Navigate to **Practice Management → Payment Plans**, select a plan, or go to `/pm/payment-plans/:planId`.
2. The summary shows total amount, installment frequency, start date, and current status badge.

* **Payment plan status** — displayed using `PAYMENT_PLAN_STATUS_LABELS` and badge variant from `PAYMENT_PLAN_STATUS_VARIANT`.
* **Frequency** — installment schedule interval as defined in `PAYMENT_PLAN_FREQUENCY_LABELS`.

## 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/PaymentPlanListPage.tsx
  * src/cores/pm/hooks/usePaymentPlans.ts
  * src/platform/permissions/constants.ts
  * src/cores/pm/pages/PaymentPlanDetailPage.tsx
  * src/cores/pm/types/statement-billing.ts
</Accordion>