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

# GFE Disputes

> Track and manage disputes filed when actual charges exceed a Good Faith Estimate by $400 or more; view dispute detail and manage status workflow.

This page lists all <Tooltip tip="Good Faith Estimate — a written cost estimate required under the No Surprises Act for self-pay and uninsured patients">GFE</Tooltip> disputes for the organization and is reached at `/pm/gfe/disputes`.

## Overview

The <Tooltip tip="Good Faith Estimate — a written cost estimate required under the No Surprises Act for self-pay and uninsured patients">GFE</Tooltip> Disputes page displays disputes filed under the <Tooltip tip="No Surprises Act — federal law requiring cost transparency for self-pay and uninsured patients">NSA</Tooltip> when actual charges exceed the estimated amount by \$400 or more (the `GFE_DISPUTE_THRESHOLD` defined in code). Records are sourced from `pm_gfe_disputes` joined with `pm_good_faith_estimates`. Each dispute card shows the variance amount, status badge, dispute date, actual total, and estimated total from the linked GFE. Clicking a card navigates to `/pm/gfe/disputes/:disputeId` for the full detail.

## Who it's for

Requires permission: `PM_PERMISSIONS.GFE_VIEW` (`pm.gfe.view`).

## Before you start

* You must hold the `pm.gfe.view` permission.
* Disputes reference existing GFEs; Good Faith Estimates must exist before disputes can be filed.

## Steps

<Steps>
  <Step title="Open GFE Disputes">
    Navigate to **Practice Management → GFE → Disputes** or go directly to `/pm/gfe/disputes`. All disputes load ordered by `dispute_date` descending.
  </Step>

  <Step title="Filter by status">
    Use the **Status** dropdown to narrow the list. Options are: **All Statuses**, **Open**, **In Review**, **Resolved**, and **Closed**.
  </Step>

  <Step title="Review dispute cards">
    Each card shows: **Variance** amount, status badge, dispute date, **Actual** total charged, and **Estimated** total from the linked GFE.
  </Step>

  <Step title="Open a dispute">
    Click any card to navigate to `/pm/gfe/disputes/:disputeId` for the full dispute detail and any available actions.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Dispute statuses">
    Four statuses are defined: **open** (destructive badge), **in\_review** (default), **resolved** (secondary), and **closed** (outline).
  </Accordion>

  <Accordion title="$400 variance threshold">
    The code constant `GFE_DISPUTE_THRESHOLD = 400` in `src/cores/pm/types/gfe.ts` represents the NSA trigger threshold. Disputes where actual charges exceed the GFE total by this amount or more are surfaced here.
  </Accordion>

  <Accordion title="Empty state">
    When no disputes match the current filter, the page shows "No disputes" with the explanation "Disputes are created when actual charges exceed the estimate by \$400 or more."
  </Accordion>
</AccordionGroup>

## Viewing a dispute

The Dispute Details screen displays a single Good Faith Estimate dispute and provides status management at route `/pm/gfe/disputes/:disputeId` (permission: `pm.gfe.view`). Status management requires `pm.gfe.manage`.

The page queries `pm_gfe_disputes` joined with `pm_good_faith_estimates` via Supabase using `organizationId` and `disputeId` as filters. The Dispute Summary card shows four values: Dispute Date, Actual Total (billed charges), Variance Amount (actual minus estimated), and Estimated Total (from the linked `pm_good_faith_estimates` record). A Resolution card appears when `resolution` text is present. Status workflow actions (gated by `pm.gfe.manage`) allow advancing through states: **Mark In Review** (from `open`), **Resolve** (from `open` or `in_review`), and **Close** (any non-closed state). These actions open `GfeDisputeResolveDialog` or call `updateDisputeStatus` directly.

1. From the GFE Disputes list (`/pm/gfe/disputes`), click a row to open the dispute detail page.
2. Check the dispute date, actual total billed, estimated total from the linked GFE, and the variance amount.
3. If a resolution was recorded, it appears in the Resolution card.
4. Use the header action buttons: **Mark In Review** (from open), **Resolve**, or **Close**. The Resolve/Close actions open the resolve dialog. Requires `pm.gfe.manage`.

| Term                                      | Meaning in code                                                  |
| ----------------------------------------- | ---------------------------------------------------------------- |
| `dispute_date`                            | Date the dispute was opened                                      |
| `actual_total`                            | The actual charges billed to the patient                         |
| `variance_amount`                         | Difference between actual charges and the GFE estimate           |
| `pm_good_faith_estimates.total_estimated` | The original estimated total from the linked GFE                 |
| `resolution`                              | Free-text resolution notes recorded when the dispute is resolved |
| `GfeDisputeStatus`                        | `open`, `in_review`, `resolved`, `closed`                        |

## 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/GfeDisputeListPage.tsx
  * src/cores/pm/hooks/useGfeDisputeList.ts
  * src/cores/pm/types/gfe.ts
  * src/cores/pm/pages/GfeDisputeDetailPage.tsx
  * src/cores/pm/hooks/useGfeDisputeMutation.ts
</Accordion>