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

# Payer Modifier Rules

> Admin page for managing payer-specific CPT modifier rules that validate charges before claim submission, with version history tracking.

This page lists and manages payer-specific modifier rules used for claim validation, accessible at the route `/pm/payer-modifier-rules`.

## Overview

The Payer Modifier Rules page is an admin interface for managing `pm_payer_modifier_rules` records, scoped to the current organization. Rules define how specific CPT modifier codes should behave for a given payer (allowed, required, forbidden, or warning) with a severity level (error or other). The table is filtered by effective date by default (expired rules are excluded unless `includeExpired` is set). A payer dropdown filter lets users narrow the list to a single payer. Users with `pm.payer-modifier-rules.manage` permission see a **New Rule** button. Each rule row has four inline actions: **Edit** (opens form dialog), **History** (opens version history dialog), **Pause/Play** (toggle active state), and **Delete** (soft-delete). Rules are sorted by `modifier_code` ascending.

## Who it's for

Requires permission `PM_PERMISSIONS.PAYER_MODIFIER_RULES_VIEW` (`pm.payer-modifier-rules.view`), enforced via both `RequirePermission` in `src/routes/pm.tsx` and `PermissionGate` wrapping the page content. Creating, editing, and deleting rules additionally requires `PM_PERMISSIONS.PAYER_MODIFIER_RULES_MANAGE` (`pm.payer-modifier-rules.manage`).

## Before you start

* Your account must hold the `pm.payer-modifier-rules.view` permission.
* Payers must be configured in Payer Management before modifier rules can be assigned to them.
* An active organization context is required; rules are org-scoped.

## Steps

<Steps>
  <Step title="Navigate to Payer Modifier Rules">
    Go to **Practice Management → Payer Modifier Rules** (route `/pm/payer-modifier-rules`). The page loads all currently-effective rules for the organization, sorted by modifier code.
  </Step>

  <Step title="Filter by payer">
    Use the **payer dropdown** to narrow the list to a specific payer. Select "All Payers" to view all rules.
  </Step>

  <Step title="Add a new rule">
    Click **New Rule** (requires `pm.payer-modifier-rules.manage`) to open the PayerModifierRuleFormDialog in create mode.
  </Step>

  <Step title="Edit an existing rule">
    Click the settings icon in the **Actions** column for any rule to open the form dialog in edit mode.
  </Step>

  <Step title="View version history">
    Click the clock icon in the **Actions** column to open the RuleVersionHistoryDialog for that rule's change log.
  </Step>

  <Step title="Toggle rule active state">
    Click the pause (⏸) or play (▶) icon to disable or enable a rule. The `changeReason` is set automatically to "Disabled by admin" or "Enabled by admin".
  </Step>

  <Step title="Delete a rule">
    Click the delete icon (🗑) in the Actions column to soft-delete the rule. The rule is removed from the list immediately.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Rule actions">
    * **allowed** — modifier is permitted for this payer/CPT combination (default badge)
    * **required** — modifier must be present (secondary badge)
    * **forbidden** — modifier must not be present (destructive badge)
    * **warning** — modifier triggers a warning but does not block (outline badge)
  </Accordion>

  <Accordion title="Rule severity">
    Rules have a `severity` field rendered as a badge: `error` = destructive badge; other values = secondary badge. Severity controls how claim scrubbing responds to a rule match.
  </Accordion>

  <Accordion title="Effective date range">
    Each rule has `effective_from` and `effective_to` dates displayed as "MMM d, yyyy – MMM d, yyyy" or "MMM d, yyyy – ∞" when ongoing. By default, only currently-effective rules are shown (expired rules excluded).
  </Accordion>

  <Accordion title="CPT code scope">
    A rule may target a specific `cpt_code` or apply to all CPT codes for the payer (displayed as "All" in the CPT column when `cpt_code` is null).
  </Accordion>

  <Accordion title="Empty state">
    When no rules match filters, an empty state displays "No modifier rules — Create payer-specific modifier rules to validate charges before submission." with a Create Rule action.
  </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/PayerModifierRulesPage.tsx
  * src/cores/pm/hooks/usePayerModifierRuleList.ts
  * src/cores/pm/hooks/usePayerList.ts
  * src/platform/permissions/constants.ts
</Accordion>