# Patient billing

Canonical page: https://docs.ovok.com/java-sdk/patient-billing

`ovok.patientBilling()` manages patients' health insurance, plans, billing accounts and invoices, stored as FHIR Coverage, Account and Invoice. The project's `PATIENT_BILLING_ENABLED` setting must be on.

## Add a patient's insurance [#add-a-patients-insurance]

```java
List<JsonNode> insurers = ovok.patientBilling().insurers().list(
        Map.of("country", "DE", "kind", "statutory", "query", "AOK"), RequestOptions.defaults());

JsonNode coverage = ovok.patientBilling().coverages().create("patient-id",
        Map.of("country", "DE", "kind", "statutory",
                "insurerIk", insurers.get(0).get("ik").asText(), "memberNumber", "A123456780"),
        RequestOptions.defaults());
```

- `kind` is `statutory`, `private` or `self-pay`. A statutory coverage names its insurer by `insurerIk` and needs a valid KVNR as `memberNumber`; a private one takes a policy number of 1 to 30 characters.
- An insurer outside Ovok's directory or an invalid member number throws `OvokValidationException`.
- Another statutory coverage in the same period throws `OvokConflictException`.
- `coverages().update(coverageId, changes, ifVersion, options)` changes a coverage only if it is still at the version you read. Leave out `ifVersion` to change it regardless.
- `coverages().remove` deletes a coverage, or cancels it when a billing account names it.

## Set a plan and record invoices [#set-a-plan-and-record-invoices]

Setting plans and recording invoices is for project admins and admin client applications.

```java
ovok.patientBilling().plans().set("patient-id",
        Map.of("plan", Map.of("system", "https://example.com/plans", "code", "monthly"),
                "period", Map.of("start", "2026-12-01")),
        RequestOptions.defaults());

ovok.patientBilling().invoices().record("patient-id", invoice, RequestOptions.defaults());
```

- `plans().set` with `{"plan": null}` ends the plan, and answers `null` when there was none to end.
- `invoices().record` updates the invoice recorded with the same identifier, so a retry is safe.

## Read accounts and invoices [#read-accounts-and-invoices]

| Call | What it does |
| --- | --- |
| `plans().retrieve(patientId, options)` | Reads the patient's plan, running or ended. Throws `OvokNotFoundException` when there is none. |
| `accounts().list(patientId, options)` | Lists the patient's billing accounts. |
| `accounts().retrieve(accountId, options)` | Reads one billing account. |
| `invoices().list(patientId, params, options)` | Lists the patient's invoices, latest first, as a `Page<JsonNode>`. |
| `invoices().retrieve(invoiceId, options)` | Reads one invoice. |

Every method is in the [`PatientBillingResource` reference](/java-sdk/reference/patient-billing-resource).

## See also [#see-also]

- [`PatientBillingResource` reference](/java-sdk/reference/patient-billing-resource): every method.
- [Patient](/java-sdk/patient): the signed-in patient's records.
