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

# Jurisdiction-Aware Billing Rules — Admin Guide

> Integration Contract: docs/architecture/integrations/ -jurisdiction-aware-billing-rules-INTEGRATION.md

**Integration Contract:** [`docs/architecture/integrations/PM-07-EN-13-jurisdiction-aware-billing-rules-INTEGRATION.md`](../architecture/integrations/jurisdiction-aware-billing-rules-integration.md)

***

## Overview

Charge-capture timed-unit thresholds, modifier conventions, IOP/PHP compliance thresholds, and program labels are now driven by the organization's **PF-96 jurisdiction profile** instead of hardcoded AHCCCS/Arizona constants.

The change is **backward compatible**: organizations on the Arizona/AHCCCS profile (or with no profile resolved) continue to behave exactly as before.

***

## What's Driven by the Jurisdiction Profile

| Area                       | Profile Field                                             | AHCCCS Default (fallback)               |
| -------------------------- | --------------------------------------------------------- | --------------------------------------- |
| Minimum billable duration  | `billing.min_billable_minutes`                            | 8 minutes                               |
| Timed-code unit length     | `billing.timed_code_unit_minutes`                         | 15 minutes                              |
| Auto-applied CPT modifiers | `billing.modifier_conventions[]`                          | Hardcoded HQ/HR/HS/95/FQ/GQ/H9/CG/U7/UB |
| IOP weekly compliance      | `clinical.iop_php_compliance.iop_min_hours_per_week` etc. | ≥ 9 hr/wk, ≥ 3 days, ≥ 3 hr/day         |
| PHP weekly compliance      | `clinical.iop_php_compliance.php_min_hours_per_week` etc. | ≥ 20 hr/wk, ≥ 5 days, ≥ 4 hr/day        |
| Program label in UI        | `display_name`                                            | "AHCCCS"                                |

> **Naming note:** the underlying database column is `pf_jurisdiction_profiles.billing_rules` (JSONB). Both `useJurisdictionProfile()` (frontend) and `pf_resolve_jurisdiction_profile()` (server) expose this JSON under the runtime field `billing.*`.

***

## Fallback Chain

The charge-capture form and the `cl-note-charge-capture` edge function resolve billing rules in this order:

1. **Jurisdiction Profile** — `billing.*` from the org's PF-96 profile, resolved by site when applicable.
2. **AHCCCS Defaults** — used when the profile RPC fails, the `billing` key is missing, or `modifier_conventions` is empty/undefined.

The posture is **fail-open / fail-safe**: charges continue to flow with AHCCCS defaults. PHI-free warnings are logged when fallback is used.

***

## Configuration

### 1. Confirm the Org's Jurisdiction Profile

Jurisdiction profiles are managed at the platform level. Confirm assignment with your platform administrator before relying on overrides. Examples:

| State      | Program (`display_name`) | Min Billable | Unit Length |
| ---------- | ------------------------ | ------------ | ----------- |
| Arizona    | AHCCCS                   | 8 min        | 15 min      |
| California | Medi-Cal                 | 8 min        | 15 min      |
| Texas      | Texas Medicaid           | 8 min        | 15 min      |

### 2. Modifier Conventions

Each entry in `billing.modifier_conventions[]` has the shape:

```json theme={null}
{
  "code": "93",
  "description": "Synchronous audio-only telehealth",
  "trigger": "telehealth_audio_only"
}
```

**When `modifier_conventions` is provided and non-empty, conventions fully drive auto-modifier assignment** — the legacy hardcoded AHCCCS modifier logic is bypassed. Be sure to include conventions for every trigger your jurisdiction needs (group, family, telehealth, court-ordered, etc.) or charges may be missing modifiers.

#### Supported Triggers

| Trigger                    | Encounter Condition                                |
| -------------------------- | -------------------------------------------------- |
| `group`                    | `isGroup === true`                                 |
| `family_with_patient`      | `isFamily && patientPresent !== false`             |
| `family_without_patient`   | `isFamily && patientPresent === false`             |
| `telehealth_audio_video`   | `isTelehealth` with audio\_video modality          |
| `telehealth_audio_only`    | `isTelehealth` with audio\_only modality           |
| `telehealth_store_forward` | `isTelehealth` with store\_forward modality        |
| `court_ordered`            | `isCourtOrdered === true`                          |
| `family_support_partner`   | `isFamilySupportPartner === true`                  |
| `u7`                       | `autoApplyU7 === true` (from `pm_module_settings`) |
| `ub`                       | `autoApplyUB === true` (from `pm_module_settings`) |

Unknown triggers are silently ignored (forward-compatible). Duplicate codes are de-duplicated.

### 3. IOP / PHP Thresholds

Override any of the following in `clinical.iop_php_compliance`:

* `iop_min_hours_per_week`, `iop_min_days_per_week`, `iop_min_hours_per_day`
* `php_min_hours_per_week`, `php_min_days_per_week`, `php_min_hours_per_day`

Omitted keys fall back to AHCCCS defaults.

### 4. Program Label

Set `display_name` to the program name shown in PM tooltips and labels (e.g., "Medi-Cal"). When unset, "AHCCCS" is shown.

***

## Arizona Parity Checklist

Arizona organizations should see **no behavioral change** after this enhancement. Validate parity:

* [ ] 7-minute encounter → 0 units (not billable hint shown).
* [ ] 8-minute encounter → 1 unit.
* [ ] 23-minute encounter → 2 units.
* [ ] 45-minute encounter → 3 units.
* [ ] Group telehealth (audio-video) encounter → modifiers `HQ`, `95`.
* [ ] Family encounter with patient present → modifier `HR`.
* [ ] Family encounter without patient → modifier `HS`.
* [ ] Court-ordered encounter → modifier `H9`.
* [ ] IOP weekly compliance flagged below 9 hr / 3 days / 3 hr/day.
* [ ] PHP weekly compliance flagged below 20 hr / 5 days / 4 hr/day.
* [ ] UI shows "AHCCCS" program label.

If any item differs, confirm the org's PF-96 profile is the Arizona/AHCCCS profile (or unset, which yields the same defaults via fallback).

***

## Operational Notes

* **Caching:** `useJurisdictionProfile()` caches per-tenant with `staleTime: 5 min`, `gcTime: 10 min`. The edge function resolves the profile once per request.
* **No new permissions:** Continues to use existing `pm.charges.create` / `pm.charges.edit`.
* **No PHI in logs:** Profile resolution failures log only the org id and a generic warning.
* **Tenant safety:** Profile reads are scoped by `organization_id` (and `site_id` when supplied) via the `pf_resolve_jurisdiction_profile()` SECURITY DEFINER RPC.

***

## Related Guides

* [Jurisdiction-Aware Filing Deadlines Admin Guide](./jurisdiction-filing-deadlines-admin-guide.md)
* [Patient Registration Jurisdiction Identifiers Admin Guide](./patient-registration-jurisdiction-identifiers-admin-guide.md)
* [Charge Capture & Fee Schedules User Guide](./charge-capture-fee-schedules-user-guide.md)
* PF-96 Spec: [`specs/pf/specs/PF-96-medicaid-state-compliance-configuration.md`](../../specs/pf/specs/PF-96-medicaid-state-compliance-configuration.md)