Patient billing

Set a patient's plan

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

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

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

Authorization

bearer
headerAuthorizationBearer <JWT>

Path Parameters

patientId*string

The patient id.

Match^[A-Za-z0-9\-.]{1,64}$

Request Body

application/json
  1. body
plan*

The plan the patient pays for; null ends the running one.

period?
Defaultnull

Response Body

The plan as set or ended.

application/json
  1. response
id*string
version*string

Send it as If-Match: W/"<version>" to change only this version.

patientId*string
status*string

active while the plan runs, cancelled once ended.

plan*
period*
Example Request
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"  }}'
Example Response
{  "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' ```