# ovok.patientBilling

Canonical page: https://docs.ovok.com/web-sdk/core/namespaces/patientbilling

Ovok stores a patient's health insurance, the plan they pay for, their billing accounts and their invoices as FHIR Coverage, Account and Invoice resources. `ovok.patientBilling` reads and writes them as flat records and checks each insurance against the insurer directory and the member-number rules. Germany is the only country supported today. The project's `PATIENT_BILLING_ENABLED` setting must be on; while it is off, every call fails with a permission error coded `PATIENT_BILLING_DISABLED`.

## Turn it on [#turn-it-on]

```ts
await ovok.projects.settings.update('PATIENT_BILLING_ENABLED', true);
```

- A caller's access policy decides who may do what: `patient_billing_coverages` rows (read, create, update, delete) for insurance, and a `patient_billing_invoices` read row for plans, accounts and invoices. The policy must also let the caller read the patient, or update the patient for insurance changes.
- Project admins and admin client applications may do everything. Only they set plans and record invoices.

## Find an insurer [#find-an-insurer]

```ts
const insurers = await ovok.patientBilling.insurers.list({ kind: 'statutory', query: 'tk' });
```

- Each insurer has a `name`, a `kind` (`statutory` or `private`) and its 9-digit `ik`. Some private insurers have no IK, so `ik` is null.
- `query` matches part of the name or the start of the IK.

## Add and change insurance [#add-and-change-insurance]

```ts
const memberNumber = 'A123456780';

if (checkMemberNumber({ country: 'DE', kind: 'statutory', value: memberNumber })) {
  await ovok.patientBilling.coverages.create(patientId, {
    country: 'DE',
    kind: 'statutory',
    insurerIk: '101575519',
    memberNumber,
    period: { start: '2025-01-01' },
    order: 1,
  });
}
```

- `kind` is `statutory`, `private` or `self-pay`. Statutory insurance needs the insurer's `insurerIk` and the KVNR from the health card. Private insurance needs `insurerIk`, or `insurerName` for an insurer without an IK, plus the policy number. Self-pay needs neither.
- `checkMemberNumber` runs the server's own rule offline, so a form can flag a typo at once. A KVNR must pass its check digit, ignoring spaces and case. A policy number must have 1 to 30 characters.
- `order` says which coverage applies first when several do: 1 is first. Two statutory coverages may not overlap in time; the second fails with a conflict error coded `COVERAGE_OVERLAP`.
- `coverages.list(patientId)` returns the patient's active coverages, in order.

```ts
const [coverage] = await ovok.patientBilling.coverages.list(patientId);

await ovok.patientBilling.coverages.update(coverage.id, { order: 2 }, { ifVersion: coverage.version });
```

- `update` changes only the fields you send. `period: null` makes the coverage open-ended. A coverage's kind never changes: remove it and add another.
- With `ifVersion`, the change applies only while the coverage is still at the version you read. Otherwise it fails with a conflict error coded `COVERAGE_VERSION_MISMATCH`.
- `remove(coverageId)` deletes the coverage. If a billing account names it, the coverage is cancelled instead, so billing history stays whole.

## Plans and invoices [Server-side] [#plans-and-invoices-server-side]

```ts
await ovok.patientBilling.plans.set(patientId, {
  plan: { system: 'https://example.com/plans', code: 'plus', display: 'Plus' },
  period: { start: '2026-11-02T10:14:00Z', end: '2026-12-02T10:14:00Z' },
});

await ovok.patientBilling.invoices.record(patientId, {
  identifier: { system: 'https://example.com/payments', value: paymentId },
  status: 'balanced',
  issuedAt: '2026-11-02T10:14:00Z',
  lines: [{ code: { system: 'https://example.com/plans', code: 'plus' } }],
  total: { value: 39, currency: 'EUR' },
});
```

- Write these from your server, with an admin client application.
- `plans.set` with `{ plan: null }` ends the running plan. It answers null when the patient had no plan to end.
- `invoices.record` is keyed by `identifier`: recording the same identifier again updates that invoice, so a retried webhook is safe. Record a refund as `status: 'cancelled'` with a `cancelledReason`.
- An invoice belongs to the patient's billing account, which Ovok creates if it is missing.

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

```ts
const plan = await ovok.patientBilling.plans.retrieve(patientId);
const accounts = await ovok.patientBilling.accounts.list(patientId);

for await (const invoice of ovok.patientBilling.invoices.list(patientId)) {
  console.log(invoice.issuedAt, invoice.status, invoice.total);
}
```

- `plans.retrieve` fails with a not-found error coded `PLAN_NOT_FOUND` when the patient has no plan.
- `invoices.list` pages lazily, latest first; `limit` sets the page size, 30 by default and at most 100.
- `accounts.retrieve(accountId)` and `invoices.retrieve(invoiceId)` read one record. The raw FHIR resources stay readable through `ovok.fhir`.
- The calls go to routes under `v1/patient-billing`.

## See also [#see-also]

- [patientBilling API reference](../reference/core/patientbilling.mdx): every method and type.
- [ovok.projects](./projects.mdx) for project settings.
- [Errors and retries](../errors-and-retries.mdx)
