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

# Billing Override Rules

> Configure payer-specific CPT mappings, modifier overrides, and suppression rules for billing suggestions in the Clinical module.

The Billing Override Rules screen lets administrators configure payer-specific billing suggestion rules, accessible at `/cl/settings/billing-overrides`.

## Overview

The page queries `pm_billing_suggestion_rules` (joined to `pm_payers`) for the current organization, filtered by `deleted_at IS NULL` and ordered by `priority` descending. Rules are split across three URL-synced tabs: "CPT Mappings" (`cpt_mapping`), "Modifier Overrides" (`modifier_override`), and "Never Suggest" (`never_suggest`). Each tab shows an active-rule count badge. Each rule row has an inline `Active` toggle (calls `toggleActive` mutation), and a kebab menu with Edit, Duplicate, and Delete actions. The "Add Rule" button (gated to `cl.billing_overrides.manage`) opens `BillingOverrideRuleFormDialog`. Deleting requires confirmation: "Delete this rule?" / "It will be removed from active suggestions but can be restored by an administrator."

## Who it's for

Requires permission: `cl.billing_overrides.view` (read); `cl.billing_overrides.manage` (create/edit/delete)

## Before you start

* You must hold `cl.billing_overrides.view` to access the page.
* Creating, editing, or deleting rules requires `cl.billing_overrides.manage`.
* Rules apply organization-wide; coordinate with billing staff before modifying.

## Steps

<Steps>
  <Step title="Navigate to Billing Override Rules">
    Go to `/cl/settings/billing-overrides`. Rules load from `pm_billing_suggestion_rules` for your organization.
  </Step>

  <Step title="Select a rule type tab">
    Choose "CPT Mappings," "Modifier Overrides," or "Never Suggest." The active count badge on each tab reflects currently active rules.
  </Step>

  <Step title="Toggle a rule active or inactive">
    Use the `Active` switch on any row to enable or disable a rule without deleting it.
  </Step>

  <Step title="Create a new rule">
    Click "Add Rule" (requires `cl.billing_overrides.manage`). The `BillingOverrideRuleFormDialog` opens with the current tab's rule type pre-selected.
  </Step>

  <Step title="Edit or duplicate an existing rule">
    Open the kebab menu on a row and select "Edit" or "Duplicate." Duplicate pre-fills the form as a copy of the selected rule.
  </Step>

  <Step title="Delete a rule">
    Select "Delete" from the kebab menu. Confirm in the dialog ("Delete this rule?") to soft-delete the record.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Tab URL sync">
    The active tab is synced to the URL via `useTabUrlState` using the `tab` query parameter. Valid values: `cpt-mappings`, `modifier-overrides`, `never-suggest`.
  </Accordion>

  <Accordion title="Empty state">
    Per tab: "No CPT mapping rules yet," "No modifier override rules yet," or "No suppression rules yet" — each with a "Create your first rule to customize billing suggestions." prompt and an "Add Rule" action.
  </Accordion>

  <Accordion title="Error state">
    If the query fails, a destructive error panel is displayed with a "Retry" button that calls `refetch()`.
  </Accordion>

  <Accordion title="Condition chips">
    The `Conditions` column renders badge chips for each non-null key in `condition_config`. The semantic meaning of these keys is not documented in the UI.
  </Accordion>

  <Accordion title="Effective date range">
    The `Effective` column displays "Always" when both `effective_date` and `end_date` are null. Otherwise it shows "From {date}" and/or "To {date}".
  </Accordion>
</AccordionGroup>

## Related

<Columns cols={2}>
  <Card title="Clinical" icon="stethoscope" href="/cl/overview">
    Overview of the Clinical 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/cl.tsx
  * src/cores/cl/pages/BillingOverrideRulesPage.tsx
  * src/cores/cl/hooks/useBillingOverrideRulesMutation.ts
</Accordion>