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

# Patient Statement Billing — Admin Guide

> Module: Practice Management (PM-16) Last Updated: 2026-02-23

**Module:** Practice Management (PM-16)\
**Last Updated:** 2026-02-23

***

## Overview

This guide covers configuration, permissions, and operational management for the Patient Statement Billing module.

## Quick Reference

| I need to…                    | Pattern                                             | Location                                              |
| ----------------------------- | --------------------------------------------------- | ----------------------------------------------------- |
| Configure billing permissions | Role-to-permission mapping for statement operations | [Permission Configuration](#permission-configuration) |
| Automate statement runs       | Scheduled cron trigger to `run-statement-cycle`     | [Scheduling (Cron)](#scheduling-cron)                 |
| Run statements manually       | Trigger on-demand statement cycle                   | [Run Types](#run-types)                               |

***

## Permission Configuration

### Permission Keys

| Key                              | Category | Description                              |
| -------------------------------- | -------- | ---------------------------------------- |
| `pm.statements.view`             | view     | View statement runs and delivery history |
| `pm.statements.generate`         | create   | Trigger statement generation cycles      |
| `pm.statements.manage`           | admin    | Full management of statement runs        |
| `pm.payment_plans.view`          | view     | View payment plans                       |
| `pm.payment_plans.create`        | create   | Create new payment plans                 |
| `pm.payment_plans.edit`          | edit     | Modify existing payment plans            |
| `pm.payment_plans.delete`        | delete   | Delete payment plans                     |
| `pm.financial_assistance.view`   | view     | View financial assistance applications   |
| `pm.financial_assistance.create` | create   | Submit new applications                  |
| `pm.financial_assistance.review` | approve  | Review (approve/deny) applications       |

### Recommended Role Assignments

| Role              | Permissions                                                                    |
| ----------------- | ------------------------------------------------------------------------------ |
| **Org Admin**     | All (auto-granted)                                                             |
| **Billing Staff** | statements.view/generate, payment\_plans.\*, financial\_assistance.view/create |
| **Collections**   | All billing + financial\_assistance.review                                     |
| **Front Desk**    | statements.view, payment\_plans.view, financial\_assistance.view               |

***

## Statement Run Configuration

### Run Types

* **On Demand:** Manually triggered by staff for immediate statement generation.
* **Scheduled:** Configured to run at specific intervals (requires cron setup).
* **Cycle End:** Triggered at the end of a billing cycle.

### Scheduling (Cron)

Statement runs can be automated via the Supabase dashboard cron or `pg_cron`:

```sql theme={null}
-- Example: Run monthly on the 1st at 6:00 AM UTC
SELECT cron.schedule(
  'monthly-statements',
  '0 6 1 * *',
  $$SELECT net.http_post(
    'https://<project-ref>.supabase.co/functions/v1/run-statement-cycle',
    '{"organization_id": "<org-id>", "run_type": "scheduled"}'::jsonb,
    '{}'::jsonb,
    '{"Content-Type": "application/json"}'::jsonb
  )$$
);
```

> **⚠️ Security:** Do not embed secrets in cron payloads. The invoked function should retrieve privileged credentials from secure server-side secret storage (environment secrets/secret manager) at runtime.

### Edge Function: `run-statement-cycle`

* **Location:** `supabase/functions/run-statement-cycle/index.ts`
* **Auth:** Requires valid JWT with org access, or service role for cron invocations.
* **Parameters:** `organization_id` (required), `run_type`, `date_range_start`, `date_range_end`, `minimum_balance`.

***

## Delivery Channels

| Channel      | Configuration Required                                                               |
| ------------ | ------------------------------------------------------------------------------------ |
| **Print**    | None (generates PDF for download)                                                    |
| **Email**    | Patient must have email on file; org email provider (Entra/Gmail) must be configured |
| **Portal**   | Patient must have portal access (PM-12)                                              |
| **Text/SMS** | SMS provider configured in CE module settings                                        |

***

## Database Tables

| Table                                  | Purpose                                   |
| -------------------------------------- | ----------------------------------------- |
| `pm_statement_runs`                    | Tracks statement generation cycles        |
| `pm_statement_deliveries`              | Append-only delivery audit log            |
| `pm_payment_plans`                     | Patient payment plan agreements           |
| `pm_financial_assistance_applications` | Charity care / sliding scale applications |

### RLS Policies

* **SELECT/INSERT/UPDATE:** Enforced via `pm_has_org_access(organization_id, auth.uid())`
* **DELETE:** Restricted to `pf_is_org_admin(auth.uid(), organization_id)`
* **pm\_statement\_deliveries:** Append-only — SELECT and INSERT only; no UPDATE or DELETE

### Data Retention

* Statement deliveries are append-only and cannot be modified or deleted by any user role.
* Statement runs and their linked statements follow standard PM data retention policies.

***

## Monitoring

### Edge Function Logs

Monitor the `run-statement-cycle` function via:

* [Supabase Edge Function Logs](https://supabase.com/dashboard/project/\<your-project-ref>/functions/run-statement-cycle/logs)

### Key Metrics

* Statements generated per run
* Delivery success/failure rates
* Average statement generation time
* Payment plan completion rates
* Financial assistance approval rates

***

## Troubleshooting

| Issue                       | Resolution                                                                                                             |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Statement run fails         | Check Edge Function logs for errors. Common causes: missing patient data, DB connection issues.                        |
| Email deliveries failing    | Verify org email provider (Entra/Gmail) sender configuration and credentials. Check `send-pending-notifications` logs. |
| Permission denied errors    | Verify user has correct role assignments in Organization Settings.                                                     |
| Statement amounts incorrect | Check pm\_patient\_statements data; verify charge capture (PM-07) is complete for the billing period.                  |

***

## Related

* [PM-16 Spec](../../specs/pm/specs/PM-16-patient-statement-generation-billing-communications.md)
* [User Guide](./patient-statement-billing-user-guide.md)
* [PM-16 Integration](../architecture/integrations/patient-statement-generation-billing-communications-integration.md)