> ## 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.

# Patient Payment Plans

> View and manage patient installment payment arrangements, including balances, frequency, and status, with server-side pagination.

This page lists all patient payment plans for the current organization and allows authorized users to create new plans, accessible at the route `/pm/patient-payment-plans`.

## Overview

The Patient Payment Plans page displays a paginated table of payment plans from the `pm_patient_payment_plans` table, scoped to the current organization. Plans are fetched 25 per page in descending creation order. The table columns are: **Patient** (truncated ID with link to detail page), **Status** (badge), **Total** (currency), **Remaining** (currency), **Installment** (currency), **Frequency**, and **Start Date**. Status values are: Active, Completed, Defaulted, Cancelled, and Paused. Frequency values are: Weekly, Biweekly, and Monthly. Users with `pm.payment-plans.create` permission see a **Create Payment Plan** button that opens the `PaymentPlanWizard`. The page is wrapped in a `PermissionGate` that requires `PM_PERMISSIONS.PAYMENT_PLANS_45_VIEW` to render at all; the route additionally enforces this via `RequirePermission`.

## Who it's for

Requires permission `PM_PERMISSIONS.PAYMENT_PLANS_45_VIEW` (`pm.payment-plans.view`), enforced both at the route level (`RequirePermission` in `src/routes/pm.tsx`) and at the component level via `PermissionGate`. Creating plans additionally requires `PM_PERMISSIONS.PAYMENT_PLANS_45_CREATE` (`pm.payment-plans.create`).

## Before you start

* Your account must hold the `pm.payment-plans.view` permission.
* Payment plans are organization-scoped; plans from other organizations are not visible.

## Steps

<Steps>
  <Step title="Navigate to Patient Payment Plans">
    Go to **Practice Management → Patient Payment Plans** (route `/pm/patient-payment-plans`). The table loads the first page of 25 plans sorted by most recently created.
  </Step>

  <Step title="Review plan details in the table">
    Each row shows patient (truncated ID), status badge, total balance, remaining balance, installment amount, frequency, and start date.
  </Step>

  <Step title="View a plan's detail page">
    Click the patient ID link in any row to navigate to `/pm/patient-payment-plans/:planId` for full plan details.
  </Step>

  <Step title="Page through results">
    If more than 25 plans exist, **Previous** and **Next** buttons appear below the table. The current page and total count are displayed.
  </Step>

  <Step title="Create a new payment plan">
    Click **Create Payment Plan** (requires `pm.payment-plans.create`) to open the Payment Plan Wizard. Complete the wizard steps and submit to create the plan.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Plan statuses">
    * **Active** — plan is in progress
    * **Completed** — all installments fulfilled
    * **Defaulted** — plan in default
    * **Cancelled** — plan was cancelled (soft-deleted)
    * **Paused** — plan temporarily paused
  </Accordion>

  <Accordion title="Installment frequencies">
    Plans support **Weekly**, **Biweekly**, and **Monthly** installment schedules.
  </Accordion>

  <Accordion title="Error state">
    If the data fetch fails, the page displays "Unable to load payment plans. Please try again." with a **Retry** button that reloads the page.
  </Accordion>

  <Accordion title="Empty state">
    When no plans exist, an empty state shows "No payment plans yet — Create a payment plan to set up installment payments for patients."
  </Accordion>
</AccordionGroup>

## 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/PatientPaymentPlanListPage.tsx
  * src/cores/pm/hooks/usePatientPaymentPlans45.ts
  * src/cores/pm/types/payment-plans-collections.ts
  * src/platform/permissions/constants.ts
</Accordion>