Set a patient's plan
- Sandbox: available
- On your own host? Choose https://{host} in the playground.
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
planis your coding of the plan;periodis 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
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" } }'bearerAuthorizationBearer <JWT>patientId*stringThe patient id.
^[A-Za-z0-9\-.]{1,64}$application/json- body
plan*The plan the patient pays for; null ends the running one.
period?nullThe plan as set or ended.
application/json- response
id*stringversion*stringSend it as If-Match: W/"<version>" to change only this version.
patientId*stringstatus*stringactive while the plan runs, cancelled once ended.
plan*period*curl -X PUT 'https://api.sandbox.ovok.com/v1/patient-billing/patients/string/plan' \ -H 'Content-Type: application/json' \ -d '{ "plan": { "system": "http://example.com", "code": "string" }}'{ "id": "string", "version": "string", "patientId": "string", "status": "string", "plan": { "system": "string", "code": "string", "display": "string" }, "period": { "start": "string", "end": "string" }}Get a patient's plan GET
Gets the app plan the patient pays for, as your server last set it: a self-pay FHIR `Coverage` with the plan as its `plan` class. **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 patient, else **403** `PATIENT_BILLING_NOT_ALLOWED` or **404** `PATIENT_BILLING_PATIENT_NOT_FOUND`. - `status` is `active` while the plan runs and `cancelled` once it ended. - A patient who never had a plan answers **404** `PLAN_NOT_FOUND`. ## Example ```bash curl 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/plan' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```
List a patient's billing accounts GET
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_invoices` `read` and let you read the patient, else **403** `PATIENT_BILLING_NOT_ALLOWED` or **404** `PATIENT_BILLING_PATIENT_NOT_FOUND`. ## Example ```bash curl 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/accounts' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```