Patient billing

Enter a charge

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

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

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 }'

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 service: the same identifier again is the same charge.

Defaultnull
clinicId*string

The clinic (Organization) that gave the service; one the patient is enrolled with.

Match^[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?integer
Range1 <= value <= 9999
Default1
priceOverride?

The unit price, instead of the price list's. Needs overrideReason.

Defaultnull
overrideReason?string

Why the price list does not apply. Required with priceOverride.

Length1 <= length <= 200
Defaultnull

Response Body

A charge with this identifier was entered 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
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 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"}'
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"}