Enter a charge
- Sandbox: available
- On your own host? Choose https://{host} in the playground.
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_chargescreateand let you read the patient, else 403PATIENT_BILLING_NOT_ALLOWEDor 404PATIENT_BILLING_PATIENT_NOT_FOUND. clinicIdmust be a clinic (Organization) the patient is enrolled with, else 422BILLING_CLINIC_INVALID.- The unit price comes from the price list, as it applies on the day of
occurredAt; without one, 422CHARGE_PRICE_MISSING.priceOverridesets the unit price instead and needs anoverrideReason. - The charge keeps its unit price, so later price changes leave it alone.
totalis the unit price timesquantity. identifieris optional. With it, the same identifier for the same patient again answers the charge already entered, with 200. A new charge answers 201 withLocation: /v1/patient-billing/charges/<id>.
Example
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 }'bearerAuthorizationBearer <JWT>patientId*stringThe patient id.
^[A-Za-z0-9\-.]{1,64}$application/json- body
identifier?Your id for the service: the same identifier again is the same charge.
nullclinicId*stringThe clinic (Organization) that gave the service; one the patient is enrolled with.
^[A-Za-z0-9\-.]{1,64}$code*The service, such as a GOÄ or EBM code.
occurredAt*|When the service was given: a day, or a date-time with its offset.
quantity?integer1 <= value <= 99991priceOverride?The unit price, instead of the price list's. Needs overrideReason.
nulloverrideReason?stringWhy the price list does not apply. Required with priceOverride.
1 <= length <= 200nullA charge with this identifier was entered before; this is it.
application/json- response
id*stringversion*stringSend it as If-Match: W/"<version>" to change only this version.
patientId*stringclinicId*stringaccountId*stringidentifier*status*stringbillable until billed; billed, not-billable or entered-in-error.
code*occurredAt*stringquantity*numberunitPrice*total*Unit price times quantity.
overrideReason*stringWhy the price list did not apply; null when it did.
enteredAt*stringcurl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/patients/string/charges' \ -H 'Content-Type: application/json' \ -d '{ "clinicId": "string", "code": { "system": "http://example.com", "code": "string" }, "occurredAt": "string"}'{ "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"}List a patient's charges GET
Lists the patient's charges, latest service first, a page at a time. **Scope:** the caller's project, with `PATIENT_BILLING_ENABLED` on. ## Behaviour - Your access policy must grant `patient_billing_charges` `read` and let you read the patient, else **403** `PATIENT_BILLING_NOT_ALLOWED` or **404** `PATIENT_BILLING_PATIENT_NOT_FOUND`. - `clinicId` lists only that clinic's charges. Every status is listed; `status` says which are still `billable`. - `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>/charges?clinicId=<clinicId>' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```
Get a charge GET
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 ```bash curl 'https://api.sandbox.ovok.com/v1/patient-billing/charges/<chargeId>' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```