Patient billing

Get a patient's plan

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

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

curl 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/plan' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'

Authorization

bearer
headerAuthorizationBearer <JWT>

Path Parameters

patientId*string

The patient id.

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

Response Body

The plan, running 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 GET 'https://api.sandbox.ovok.com/v1/patient-billing/patients/string/plan'
Example Response
{  "id": "string",  "version": "string",  "patientId": "string",  "status": "string",  "plan": {    "system": "string",    "code": "string",    "display": "string"  },  "period": {    "start": "string",    "end": "string"  }}

Remove a coverage DELETE

Removes a coverage from the patient's insurance. The others are renumbered in the same transaction. **Scope:** the caller's project, with `PATIENT_BILLING_ENABLED` on. ## Behaviour - Your access policy must grant `patient_billing_coverages` `delete` and let you update the coverage's patient, else **403** `PATIENT_BILLING_NOT_ALLOWED`. - A coverage no billing account names is deleted. One an account names is cancelled instead, its period ending today, so billing history stays whole. - Changes to one patient's coverages run one at a time: another still running answers **409**; send yours again. - Answers **204** either way; the coverage no longer appears in the patient's list. ## Example ```bash curl -X DELETE 'https://api.sandbox.ovok.com/v1/patient-billing/coverages/<coverageId>' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```

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