Patient billing

Issue an invoice from charges

  • Sandbox: available
  • On your own host? Choose https://{host} in the playground.
POST
/v1/patient-billing/patients/{patientId}/invoices/issue

Issues an invoice of the patient's billable charges at one clinic, for example a private GOÄ bill. The invoice is a FHIR Invoice from the clinic to the patient, a line per charge with its price; the charges turn billed in the same commit.

Scope: the caller's project, with PATIENT_BILLING_ENABLED on.

Behaviour

  • Your access policy must grant patient_billing_invoices create and let you read the patient, else 403 PATIENT_BILLING_NOT_ALLOWED or 404 PATIENT_BILLING_PATIENT_NOT_FOUND. The invoice shows the charges it bills, so this row reads them too.
  • clinicId must be a clinic the patient is enrolled with, else 422 BILLING_CLINIC_INVALID.
  • chargeIds names the charges to bill; left out, every billable charge at the clinic is billed, 49 at most (422 CHARGES_TOO_MANY). A charge named that is not billable there answers 409 CHARGE_NOT_BILLABLE; nothing billable at all, 409 NO_BILLABLE_CHARGES.
  • The charges must share one currency, else 422 CHARGE_CURRENCY_MIXED.
  • identifier, such as your invoice number, is optional. With it, the same identifier for the same patient again answers the invoice already issued, with 200. A new invoice answers 201 with Location: /v1/patient-billing/invoices/<id>.
  • Changes to one patient's charges run one at a time: another still running, or a charge changed while billing, answers 409; send yours again.

Example

curl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/invoices/issue' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \  -H 'Content-Type: application/json' \  -d '{ "identifier": { "system": "https://example.com/invoice-numbers", "value": "2026-000123" }, "clinicId": "<clinicId>", "chargeIds": null, "issuedAt": null }'

Authorization

bearer
headerAuthorizationBearer <JWT>

Path Parameters

patientId*string

The patient id.

Match^[A-Za-z0-9\-.]{1,64}$

Request Body

application/json
  1. body
identifier?

Your id for the invoice, such as its invoice number: the same identifier again is the same invoice.

Defaultnull
clinicId*string

The clinic whose charges are billed.

Match^[A-Za-z0-9\-.]{1,64}$
chargeIds?array<>

The billable charges to bill; every billable charge at the clinic when left out, 49 at most.

Items1 <= items <= 49
Defaultnull
issuedAt?string

When issued; now when left out.

Formatdate-time
Defaultnull

Response Body

An invoice with this identifier was issued before; this is it.

application/json
  1. response
id*string
version*string

Send it as If-Match: W/"<version>" to change only this version.

patientId*string
identifier*
status*string
cancelledReason*string
issuedAt*string
accountId*string
clinicId*string

The clinic that issued it from charges; null for a recorded payment.

lines*array<>
total*
Example Request
curl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/patients/string/invoices/issue' \  -H 'Content-Type: application/json' \  -d '{  "clinicId": "string"}'
Example Response
{  "id": "string",  "version": "string",  "patientId": "string",  "identifier": {    "system": "string",    "value": "string"  },  "status": "string",  "cancelledReason": "string",  "issuedAt": "string",  "accountId": "string",  "clinicId": "string",  "lines": [    {      "code": {        "system": "string",        "code": "string",        "display": "string"      },      "chargeId": "string",      "amount": {        "value": 0,        "currency": "string"      }    }  ],  "total": {    "value": 0,    "currency": "string"  }}

Record an invoice POST

Records an invoice for a paid period, from your server's payment or store webhooks. The invoice is a FHIR `Invoice` on the patient's billing account, which Ovok makes if it is missing. **Scope:** a project admin or an admin ClientApplication, in a project with `PATIENT_BILLING_ENABLED` on. Anyone else: **403** `PATIENT_BILLING_NOT_ALLOWED`. ## Behaviour - `identifier` is your id for the payment, such as your payment provider's. The same identifier for the same patient again is the same invoice: it answers **200** and is written over when it changed, so a retried webhook never records it twice. - A new identifier answers **201** with `Location: /v1/patient-billing/invoices/<id>`. - `status` is `issued`, `balanced` (paid) or `cancelled`, for example after a refund, with `cancelledReason`. - `lines` say what was billed, such as the plan paid for; `total` is the gross amount. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/invoices' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "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" } }' ```

Get an invoice GET

Gets one invoice. **Scope:** the caller's project, with `PATIENT_BILLING_ENABLED` on. ## Behaviour - Your access policy must grant `patient_billing_invoices` `read` and let you read the invoice's patient. An invoice you cannot see answers **404** `INVOICE_NOT_FOUND`. - An invoice issued from charges names its `clinicId`, and each line its `chargeId` and `amount`. A recorded payment has neither. ## Example ```bash curl 'https://api.sandbox.ovok.com/v1/patient-billing/invoices/<invoiceId>' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```