Record an invoice
- Sandbox: available
- On your own host? Choose https://{host} in the playground.
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
identifieris 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>. statusisissued,balanced(paid) orcancelled, for example after a refund, withcancelledReason.linessay what was billed, such as the plan paid for;totalis the gross amount.
Example
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" } }'bearerAuthorizationBearer <JWT>patientId*stringThe patient id.
^[A-Za-z0-9\-.]{1,64}$application/json- body
identifier*Your id for the payment: the same identifier again is the same invoice.
status*string"issued""balanced""cancelled"cancelledReason?string1 <= length <= 200nullissuedAt*stringWhen it was issued or paid.
date-timelines*array<>What was billed, such as the plan paid for.
1 <= items <= 50total?nullAn invoice with this identifier was recorded before; it now reads as sent.
application/json- response
id*stringversion*stringSend it as If-Match: W/"<version>" to change only this version.
patientId*stringidentifier*status*stringcancelledReason*stringissuedAt*stringaccountId*stringclinicId*stringThe clinic that issued it from charges; null for a recorded payment.
lines*array<>total*curl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/patients/string/invoices' \ -H 'Content-Type: application/json' \ -d '{ "identifier": { "system": "http://example.com", "value": "string" }, "status": "issued", "issuedAt": "2019-08-24T14:15:22Z", "lines": [ { "code": { "system": "http://example.com", "code": "string" } } ]}'{ "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" }}List a patient's invoices GET
Lists the patient's invoices, latest first, a page at a time. **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 patient, else **403** `PATIENT_BILLING_NOT_ALLOWED` or **404** `PATIENT_BILLING_PATIENT_NOT_FOUND`. - `limit` is 1 to 100 (30 when left out). Send `nextCursor` back as `cursor` for the next page; a cursor no page gave answers **400** `PATIENT_BILLING_CURSOR_INVALID`. ## Example ```bash curl 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/invoices?limit=30' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```
Issue an invoice from charges POST
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 ```bash 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 }' ```