Patient billing

Get a charge

  • Sandbox: available
  • On your own host? Choose https://{host} in the playground.
GET
/v1/patient-billing/charges/{chargeId}

Reads one charge.

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

Behaviour

  • Your access policy must grant patient_billing_charges read, else 403 PATIENT_BILLING_NOT_ALLOWED.
  • A charge whose patient you cannot read answers 404 CHARGE_NOT_FOUND.

Example

curl 'https://api.sandbox.ovok.com/v1/patient-billing/charges/<chargeId>' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'

Authorization

bearer
headerAuthorizationBearer <JWT>

Path Parameters

chargeId*string

The charge id.

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

Response Body

The charge.

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

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

patientId*string
clinicId*string
accountId*string
identifier*
status*string

billable until billed; billed, not-billable or entered-in-error.

code*
occurredAt*string
quantity*number
unitPrice*
total*

Unit price times quantity.

overrideReason*string

Why the price list did not apply; null when it did.

enteredAt*string
Example Request
curl -X GET 'https://api.sandbox.ovok.com/v1/patient-billing/charges/string'
Example Response
{  "id": "string",  "version": "string",  "patientId": "string",  "clinicId": "string",  "accountId": "string",  "identifier": {    "system": "string",    "value": "string"  },  "status": "string",  "code": {    "system": "string",    "code": "string",    "display": "string"  },  "occurredAt": "string",  "quantity": 0,  "unitPrice": {    "value": 0,    "currency": "string"  },  "total": {    "value": 0,    "currency": "string"  },  "overrideReason": "string",  "enteredAt": "string"}

Enter a charge POST

Enters a charge: one billable service a clinic gave the patient, as a FHIR `ChargeItem`. It goes on the account the clinic keeps for the patient, which Ovok makes with the first charge and which names the patient's coverages in order. **Scope:** the caller's project, with `PATIENT_BILLING_ENABLED` on. ## Behaviour - Your access policy must grant `patient_billing_charges` `create` and let you read the patient, else **403** `PATIENT_BILLING_NOT_ALLOWED` or **404** `PATIENT_BILLING_PATIENT_NOT_FOUND`. - `clinicId` must be a clinic (Organization) the patient is enrolled with, else **422** `BILLING_CLINIC_INVALID`. - The unit price comes from the price list, as it applies on the day of `occurredAt`; without one, **422** `CHARGE_PRICE_MISSING`. `priceOverride` sets the unit price instead and needs an `overrideReason`. - The charge keeps its unit price, so later price changes leave it alone. `total` is the unit price times `quantity`. - `identifier` is optional. With it, the same identifier for the same patient again answers the charge already entered, with **200**. A new charge answers **201** with `Location: /v1/patient-billing/charges/<id>`. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/charges' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "clinicId": "<clinicId>", "code": { "system": "http://fhir.de/CodeSystem/kbv/ebm", "code": "03040", "display": null }, "occurredAt": "2026-11-18", "quantity": 1 }' ```

Change a charge PATCH

Changes a charge that is not billed yet: its status, its quantity or its price. Fields left out stay as they are. **Scope:** the caller's project, with `PATIENT_BILLING_ENABLED` on. ## Behaviour - Your access policy must grant `patient_billing_charges` `update` and let you read the charge's patient, else **403** `PATIENT_BILLING_NOT_ALLOWED`. A charge you cannot see answers **404** `CHARGE_NOT_FOUND`. - `status` is `billable`, `not-billable` (not to be billed) or `entered-in-error`. A billed charge no longer changes: **409** `CHARGE_BILLED`. - `priceOverride` sets the unit price and needs an `overrideReason`; `priceOverride: null` returns the charge to the price list, as it applies on the day of the service, else **422** `CHARGE_PRICE_MISSING`. - Changes to one patient's charges run one at a time: another still running answers **409**; send yours again. - `If-Match: W/"<version>"` is optional. With it, the change lands only on that version, else **412** `CHARGE_VERSION_MISMATCH`. ## Example ```bash curl -X PATCH 'https://api.sandbox.ovok.com/v1/patient-billing/charges/<chargeId>' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'If-Match: W/"1"' \ -H 'Content-Type: application/json' \ -d '{ "status": "not-billable" }' ```