Skip to main content

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.

Last Updated: 2026-05-04 Spec: specs/pm/specs/PM-07-EN-13-jurisdiction-aware-billing-rules.md Integration Contract: docs/architecture/integrations/PM-07-EN-13-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

AreaProfile FieldAHCCCS Default (fallback)
Minimum billable durationbilling.min_billable_minutes8 minutes
Timed-code unit lengthbilling.timed_code_unit_minutes15 minutes
Auto-applied CPT modifiersbilling.modifier_conventions[]Hardcoded HQ/HR/HS/95/FQ/GQ/H9/CG/U7/UB
IOP weekly complianceclinical.iop_php_compliance.iop_min_hours_per_week etc.≥ 9 hr/wk, ≥ 3 days, ≥ 3 hr/day
PHP weekly complianceclinical.iop_php_compliance.php_min_hours_per_week etc.≥ 20 hr/wk, ≥ 5 days, ≥ 4 hr/day
Program label in UIdisplay_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:
StateProgram (display_name)Min BillableUnit Length
ArizonaAHCCCS8 min15 min
CaliforniaMedi-Cal8 min15 min
TexasTexas Medicaid8 min15 min

​
2. Modifier Conventions

Each entry in billing.modifier_conventions[] has the shape: 
{
  "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

TriggerEncounter Condition
groupisGroup === true
family_with_patientisFamily && patientPresent !== false
family_without_patientisFamily && patientPresent === false
telehealth_audio_videoisTelehealth with audio_video modality
telehealth_audio_onlyisTelehealth with audio_only modality
telehealth_store_forwardisTelehealth with store_forward modality
court_orderedisCourtOrdered === true
family_support_partnerisFamilySupportPartner === true
u7autoApplyU7 === true (from pm_module_settings)
ubautoApplyUB === 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.