Get a charge
- Sandbox: available
- On your own host? Choose https://{host} in the playground.
Reads one charge.
Scope: the caller's project, with PATIENT_BILLING_ENABLED on.
Behaviour
- Your access policy must grant
patient_billing_chargesread, else 403PATIENT_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'bearerAuthorizationBearer <JWT>chargeId*stringThe charge id.
^[A-Za-z0-9\-.]{1,64}$The charge.
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 GET 'https://api.sandbox.ovok.com/v1/patient-billing/charges/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"}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" }' ```