List a patient's billing accounts
- Sandbox: available
- On your own host? Choose https://{host} in the playground.
Lists the patient's billing accounts: FHIR Account resources of type PBILLACCT whose subject is the patient. Ovok makes one per patient, with the first plan or invoice, and it names the plan coverage. Each clinic that enters a charge for the patient gets its own account too: clinicId names the clinic, and coverageIds the patient's coverages in order.
Scope: the caller's project, with PATIENT_BILLING_ENABLED on.
Behaviour
- Your access policy must grant
patient_billing_invoicesreadand let you read the patient, else 403PATIENT_BILLING_NOT_ALLOWEDor 404PATIENT_BILLING_PATIENT_NOT_FOUND.
Example
curl 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/accounts' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'bearerAuthorizationBearer <JWT>patientId*stringThe patient id.
^[A-Za-z0-9\-.]{1,64}$The patient's billing accounts.
application/json- response
items*array<>curl -X GET 'https://api.sandbox.ovok.com/v1/patient-billing/patients/string/accounts'{ "items": [ { "id": "string", "version": "string", "patientId": "string", "status": "string", "clinicId": "string", "coverageIds": [ "string" ] } ]}Set a patient's plan PUT
Sets the app plan the patient pays for, from your server's payment or store webhooks, or ends it. Ovok keeps one plan `Coverage` per patient, names it on the patient's billing `Account`, and tags the `Patient` with the plan so `_tag` finds patients by plan. **Scope:** a project admin or an admin ClientApplication, in a project with `PATIENT_BILLING_ENABLED` on. Anyone else: **403** `PATIENT_BILLING_NOT_ALLOWED`. ## Behaviour - `plan` is your coding of the plan; `period` is the paid period, and may not end before it starts (**422**). The plan is written as sent, so send the whole of it every time. - The first plan answers **201** with `Location`; later ones **200**. Sending the same plan again changes nothing. - `{ "plan": null }` ends the plan: it is cancelled, its period ending no later than now, and the tag is removed. A patient with no plan answers **204**. - Retries and late webhooks land on the same records. ## Example ```bash curl -X PUT 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/plan' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "plan": { "system": "https://example.com/plans", "code": "plus", "display": "Plus" }, "period": { "start": "2026-11-02T10:14:00Z", "end": "2026-12-02T10:14:00Z" } }' ```
Get a billing account GET
Gets one billing account. **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 account's patient. An account you cannot see answers **404** `ACCOUNT_NOT_FOUND`. ## Example ```bash curl 'https://api.sandbox.ovok.com/v1/patient-billing/accounts/<accountId>' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```