# Plans, accounts and invoices

Canonical page: https://docs.ovok.com/patient-billing/plans-and-invoices

The app plan is the plan a patient pays your app for. Your server records it, and an invoice for each paid period, when your payment or store provider calls your webhook. Patients and clinic staff then read the plan, the billing account and the invoices.

Ovok stores the plan as a self-pay FHIR `Coverage`, the account as an `Account` and each payment as an `Invoice`. Insurance is separate: see [Insurance](/patient-billing/insurance).

## Write from your server [#write-from-your-server]

Only a project admin or an admin [ClientApplication](/applications#admin) writes plans and invoices. No access policy row grants it, and anyone else gets `403` [`PATIENT_BILLING_NOT_ALLOWED`](/errors/patient-billing-not-allowed). Exchange the client's id and secret for a token with `client_credentials` at `POST /oauth2/token`, and keep the token on your server.

The examples use `PATIENT_ID` for the patient's id, `SERVER_TOKEN` for that token and `OVOK_TOKEN` for a patient's or staff member's token.

```mermaid
flowchart LR
  provider[Payment or store provider] -->|Webhook| server[Your server]
  server -->|PUT plan| api["/v1/patient-billing"]
  server -->|POST invoice| api
  app[Patient app or clinic] -->|GET plan, accounts, invoices| api
```

## Handle a payment webhook [#handle-a-payment-webhook]

When your provider reports a paid period:

1. Look up the Ovok patient id for the payer.
2. [Set the plan](#set-or-end-the-plan) with the plan's code and the paid period.
3. [Record the invoice](#record-an-invoice) with your provider's payment id as its `identifier`.

When it reports a refund, record the same `identifier` again with `status` `cancelled`. When access to the plan ends, set the plan to `null`.

Both calls are safe to repeat. The plan is one record per patient, and an invoice is found by its identifier, so a retried or late webhook lands on the records it already made. Ovok writes what you send, so skip a webhook older than the last one you applied.

## Set or end the plan [#set-or-end-the-plan]

Sets the plan the patient pays for, or ends it. Ovok keeps one plan per patient, names it on the patient's billing account, and tags the `Patient` with the plan so a `_tag` search finds patients by plan.

```bash
curl --request PUT \
  --url "https://api.sandbox.ovok.com/v1/patient-billing/patients/${PATIENT_ID}/plan" \
  --header "Authorization: Bearer ${SERVER_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{
    "plan": {
      "system": "https://example.com/plans",
      "code": "plus",
      "display": "Plus"
    },
    "period": {
      "start": "2026-11-02T10:14:00Z",
      "end": "2026-12-02T10:14:00Z"
    }
  }'
```

| Body field | Required | Description |
| --- | --- | --- |
| `plan.system` | Yes | Your code system, a URL such as `https://example.com/plans`. |
| `plan.code` | Yes | The plan's code, up to 64 characters. |
| `plan.display` | No | The plan's name for people. |
| `period.start` | With `period` | When the paid period began, a date-time with an offset. |
| `period.end` | No | When the paid period runs out. It may not be before `start`. |

Send the whole plan every time: Ovok writes it as sent. The first plan answers `201` with `Location: /v1/patient-billing/patients/<patientId>/plan`, and later ones answer `200`. Sending the same plan again changes nothing.

```json
{
  "id": "e2c6a9b4-5d17-4f08-a3b1-7c9d0e4f2a56",
  "version": "1",
  "patientId": "5f2c9a1e-8d3b-4a7e-b6c4-2e9f1d0a7c38",
  "status": "active",
  "plan": { "system": "https://example.com/plans", "code": "plus", "display": "Plus" },
  "period": { "start": "2026-11-02T10:14:00Z", "end": "2026-12-02T10:14:00Z" }
}
```

### End the plan [#end-the-plan]

Send `{ "plan": null }` to end the plan. It becomes `cancelled`, its period ends no later than now, and the tag is removed from the patient. A patient with no plan answers `204`.

```bash
curl --request PUT \
  --url "https://api.sandbox.ovok.com/v1/patient-billing/patients/${PATIENT_ID}/plan" \
  --header "Authorization: Bearer ${SERVER_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{ "plan": null }'
```

A patient the caller cannot see answers `404` [`PATIENT_BILLING_PATIENT_NOT_FOUND`](/errors/patient-billing-patient-not-found). A body that fails validation, including a period that ends before it starts, answers `422`.

## Get the plan [#get-the-plan]

Returns the plan as your server last set it, running or ended. `status` is `active` while the plan runs and `cancelled` once it ended. The caller needs the `patient_billing_invoices:read` row; see [Access](/patient-billing/access).

```bash
curl "https://api.sandbox.ovok.com/v1/patient-billing/patients/${PATIENT_ID}/plan" \
  --header "Authorization: Bearer ${OVOK_TOKEN}"
```

A patient who never had a plan answers `404` [`PLAN_NOT_FOUND`](/errors/plan-not-found).

## Record an invoice [#record-an-invoice]

Records the invoice for a paid period on the patient's billing account, which Ovok creates if it is missing.

```bash
curl --request POST \
  --url "https://api.sandbox.ovok.com/v1/patient-billing/patients/${PATIENT_ID}/invoices" \
  --header "Authorization: Bearer ${SERVER_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{
    "identifier": { "system": "https://example.com/payments", "value": "tr_7UhSN1zuXS" },
    "status": "balanced",
    "cancelledReason": null,
    "issuedAt": "2026-11-02T10:14:00Z",
    "lines": [
      { "code": { "system": "https://example.com/plans", "code": "plus", "display": "Plus" } }
    ],
    "total": { "value": 39, "currency": "EUR" }
  }'
```

| Body field | Required | Description |
| --- | --- | --- |
| `identifier` | Yes | Your id for the payment: a `system` URL and a `value` of up to 200 characters, without spaces, commas, pipes, backslashes or dollar signs. |
| `status` | Yes | `issued`, `balanced` for paid, or `cancelled`, for example after a refund. |
| `cancelledReason` | No | Why the invoice was cancelled. |
| `issuedAt` | Yes | When it was issued or paid, a date-time with an offset. |
| `lines` | Yes | 1 to 50 lines, each with a `code` (`system`, `code` and optional `display`) naming what was billed, such as the plan. |
| `total` | No | The gross amount: `value` and an ISO 4217 `currency`. |

A new `identifier` answers `201` with `Location: /v1/patient-billing/invoices/<id>`. The same `identifier` for the same patient again is the same invoice: it answers `200`, and Ovok writes it over when it changed, so a retried webhook never records a payment twice.

```json
{
  "id": "c4a1e8f2-9b3d-4e60-8f27-1a5d7b9c0e43",
  "version": "1",
  "patientId": "5f2c9a1e-8d3b-4a7e-b6c4-2e9f1d0a7c38",
  "identifier": { "system": "https://example.com/payments", "value": "tr_7UhSN1zuXS" },
  "status": "balanced",
  "cancelledReason": null,
  "issuedAt": "2026-11-02T10:14:00Z",
  "accountId": "a8d3f5c1-2b6e-4719-9c0a-e4f7b1d2635a",
  "lines": [
    { "code": { "system": "https://example.com/plans", "code": "plus", "display": "Plus" } }
  ],
  "total": { "value": 39, "currency": "EUR" }
}
```

## List the invoices [#list-the-invoices]

Returns the patient's invoices, latest first, a page at a time. The caller needs `patient_billing_invoices:read`.

```bash
curl --get "https://api.sandbox.ovok.com/v1/patient-billing/patients/${PATIENT_ID}/invoices" \
  --data-urlencode 'limit=30' \
  --header "Authorization: Bearer ${OVOK_TOKEN}"
```

| Query parameter | Description |
| --- | --- |
| `limit` | 1 to 100 invoices per page. 30 when left out. |
| `cursor` | The `nextCursor` of the previous page, unchanged. |

The answer is `{ "items": [ ... ], "nextCursor": "..." }`. `nextCursor` is `null` on the last page. A cursor that no page gave answers `400` [`PATIENT_BILLING_CURSOR_INVALID`](/errors/patient-billing-cursor-invalid).

## Get an invoice [#get-an-invoice]

Returns one invoice by id. An invoice the caller cannot see answers `404` [`INVOICE_NOT_FOUND`](/errors/invoice-not-found).

```bash
curl "https://api.sandbox.ovok.com/v1/patient-billing/invoices/${INVOICE_ID}" \
  --header "Authorization: Bearer ${OVOK_TOKEN}"
```

## Read the billing account [#read-the-billing-account]

The billing account is a FHIR `Account` of type `PBILLACCT` whose subject is the patient. Ovok creates it with the patient's first plan or invoice, and it names the plan's coverage. The caller needs `patient_billing_invoices:read`.

```bash
curl "https://api.sandbox.ovok.com/v1/patient-billing/patients/${PATIENT_ID}/accounts" \
  --header "Authorization: Bearer ${OVOK_TOKEN}"
```

The answer is `{ "items": [ ... ] }`. `GET /v1/patient-billing/accounts/:accountId` returns one account, or `404` [`ACCOUNT_NOT_FOUND`](/errors/account-not-found).

```json
{
  "id": "a8d3f5c1-2b6e-4719-9c0a-e4f7b1d2635a",
  "version": "1",
  "patientId": "5f2c9a1e-8d3b-4a7e-b6c4-2e9f1d0a7c38",
  "status": "active",
  "coverageIds": ["e2c6a9b4-5d17-4f08-a3b1-7c9d0e4f2a56"]
}
```

`coverageIds` lists the coverages the account bills against, first first.

## What Ovok stores [#what-ovok-stores]

Each patient has one plan `Coverage` and one billing `Account`, found by an identifier valued with the patient's id. Invoices are found by your own identifier.

| Record | FHIR resource | Identifier system |
| --- | --- | --- |
| Plan | `Coverage` of the self-pay type `pay`, with your plan as its `plan` class | `https://api.ovok.com/fhir/StructureDefinition/patient-billing-plan` |
| Billing account | `Account` of type `PBILLACCT` | `https://api.ovok.com/fhir/StructureDefinition/patient-billing-account` |
| Invoice | `Invoice` on the billing account | The `system` and `value` you sent |

The plan's code system sits in the extension `https://api.ovok.com/fhir/StructureDefinition/patient-billing-plan-system` on the coverage's `class`. The `Patient` carries the plan as a tag, so this finds the patients on a plan:

```bash
curl --get 'https://api.sandbox.ovok.com/fhir/R4/Patient' \
  --data-urlencode '_tag=https://example.com/plans|plus' \
  --header "Authorization: Bearer ${OVOK_TOKEN}"
```

The coverage is the record of the plan; the tag is a search convenience.

## See also [#see-also]

- [Patient billing and insurance](/patient-billing)
- [Insurance](/patient-billing/insurance)
- [Access](/patient-billing/access)
