Skip to main content
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

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:

​
2. Modifier Conventions

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

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.