Plans, accounts and invoices
Record the plan a patient pays your app for and each payment from your server's webhooks, and read the patient's plan, billing account and invoices.
The app plan is the plan a patient pays your app for. Your server records it, and an invoice for each paid period, when your payment or store provider calls your webhook. Patients and clinic staff then read the plan, the billing account and the invoices.
Ovok stores the plan as a self-pay FHIR Coverage, the account as an Account and each payment as an Invoice. Insurance is separate: see Insurance.
Write from your server
Only a project admin or an admin ClientApplication writes plans and invoices. No access policy row grants it, and anyone else gets 403 PATIENT_BILLING_NOT_ALLOWED. Exchange the client's id and secret for a token with client_credentials at POST /oauth2/token, and keep the token on your server.
The examples use PATIENT_ID for the patient's id, SERVER_TOKEN for that token and OVOK_TOKEN for a patient's or staff member's token.
Handle a payment webhook
When your provider reports a paid period:
- Look up the Ovok patient id for the payer.
- Set the plan with the plan's code and the paid period.
- Record the invoice with your provider's payment id as its
identifier.
When it reports a refund, record the same identifier again with status cancelled. When access to the plan ends, set the plan to null.
Both calls are safe to repeat. The plan is one record per patient, and an invoice is found by its identifier, so a retried or late webhook lands on the records it already made. Ovok writes what you send, so skip a webhook older than the last one you applied.
Set or end the plan
Sets the plan the patient pays for, or ends it. Ovok keeps one plan per patient, names it on the patient's billing account, and tags the Patient with the plan so a _tag search finds patients by plan.
curl --request PUT \
--url "https://api.sandbox.ovok.com/v1/patient-billing/patients/${PATIENT_ID}/plan" \
--header "Authorization: Bearer ${SERVER_TOKEN}" \
--header 'Content-Type: application/json' \
--data '{
"plan": {
"system": "https://example.com/plans",
"code": "plus",
"display": "Plus"
},
"period": {
"start": "2026-11-02T10:14:00Z",
"end": "2026-12-02T10:14:00Z"
}
}'| Body field | Required | Description |
|---|---|---|
plan.system | Yes | Your code system, a URL such as https://example.com/plans. |
plan.code | Yes | The plan's code, up to 64 characters. |
plan.display | No | The plan's name for people. |
period.start | With period | When the paid period began, a date-time with an offset. |
period.end | No | When the paid period runs out. It may not be before start. |
Send the whole plan every time: Ovok writes it as sent. The first plan answers 201 with Location: /v1/patient-billing/patients/<patientId>/plan, and later ones answer 200. Sending the same plan again changes nothing.
{
"id": "e2c6a9b4-5d17-4f08-a3b1-7c9d0e4f2a56",
"version": "1",
"patientId": "5f2c9a1e-8d3b-4a7e-b6c4-2e9f1d0a7c38",
"status": "active",
"plan": { "system": "https://example.com/plans", "code": "plus", "display": "Plus" },
"period": { "start": "2026-11-02T10:14:00Z", "end": "2026-12-02T10:14:00Z" }
}End the plan
Send { "plan": null } to end the plan. It becomes cancelled, its period ends no later than now, and the tag is removed from the patient. A patient with no plan answers 204.
curl --request PUT \
--url "https://api.sandbox.ovok.com/v1/patient-billing/patients/${PATIENT_ID}/plan" \
--header "Authorization: Bearer ${SERVER_TOKEN}" \
--header 'Content-Type: application/json' \
--data '{ "plan": null }'A patient the caller cannot see answers 404 PATIENT_BILLING_PATIENT_NOT_FOUND. A body that fails validation, including a period that ends before it starts, answers 422.
Get the plan
Returns the plan as your server last set it, running or ended. status is active while the plan runs and cancelled once it ended. The caller needs the patient_billing_invoices:read row; see Access.
curl "https://api.sandbox.ovok.com/v1/patient-billing/patients/${PATIENT_ID}/plan" \
--header "Authorization: Bearer ${OVOK_TOKEN}"A patient who never had a plan answers 404 PLAN_NOT_FOUND.
Record an invoice
Records the invoice for a paid period on the patient's billing account, which Ovok creates if it is missing.
curl --request POST \
--url "https://api.sandbox.ovok.com/v1/patient-billing/patients/${PATIENT_ID}/invoices" \
--header "Authorization: Bearer ${SERVER_TOKEN}" \
--header 'Content-Type: application/json' \
--data '{
"identifier": { "system": "https://example.com/payments", "value": "tr_7UhSN1zuXS" },
"status": "balanced",
"cancelledReason": null,
"issuedAt": "2026-11-02T10:14:00Z",
"lines": [
{ "code": { "system": "https://example.com/plans", "code": "plus", "display": "Plus" } }
],
"total": { "value": 39, "currency": "EUR" }
}'| Body field | Required | Description |
|---|---|---|
identifier | Yes | Your id for the payment: a system URL and a value of up to 200 characters, without spaces, commas, pipes, backslashes or dollar signs. |
status | Yes | issued, balanced for paid, or cancelled, for example after a refund. |
cancelledReason | No | Why the invoice was cancelled. |
issuedAt | Yes | When it was issued or paid, a date-time with an offset. |
lines | Yes | 1 to 50 lines, each with a code (system, code and optional display) naming what was billed, such as the plan. |
total | No | The gross amount: value and an ISO 4217 currency. |
A new identifier answers 201 with Location: /v1/patient-billing/invoices/<id>. The same identifier for the same patient again is the same invoice: it answers 200, and Ovok writes it over when it changed, so a retried webhook never records a payment twice.
{
"id": "c4a1e8f2-9b3d-4e60-8f27-1a5d7b9c0e43",
"version": "1",
"patientId": "5f2c9a1e-8d3b-4a7e-b6c4-2e9f1d0a7c38",
"identifier": { "system": "https://example.com/payments", "value": "tr_7UhSN1zuXS" },
"status": "balanced",
"cancelledReason": null,
"issuedAt": "2026-11-02T10:14:00Z",
"accountId": "a8d3f5c1-2b6e-4719-9c0a-e4f7b1d2635a",
"lines": [
{ "code": { "system": "https://example.com/plans", "code": "plus", "display": "Plus" } }
],
"total": { "value": 39, "currency": "EUR" }
}List the invoices
Returns the patient's invoices, latest first, a page at a time. The caller needs patient_billing_invoices:read.
curl --get "https://api.sandbox.ovok.com/v1/patient-billing/patients/${PATIENT_ID}/invoices" \
--data-urlencode 'limit=30' \
--header "Authorization: Bearer ${OVOK_TOKEN}"| Query parameter | Description |
|---|---|
limit | 1 to 100 invoices per page. 30 when left out. |
cursor | The nextCursor of the previous page, unchanged. |
The answer is { "items": [ ... ], "nextCursor": "..." }. nextCursor is null on the last page. A cursor that no page gave answers 400 PATIENT_BILLING_CURSOR_INVALID.
Get an invoice
Returns one invoice by id. An invoice the caller cannot see answers 404 INVOICE_NOT_FOUND.
curl "https://api.sandbox.ovok.com/v1/patient-billing/invoices/${INVOICE_ID}" \
--header "Authorization: Bearer ${OVOK_TOKEN}"Read the billing account
The billing account is a FHIR Account of type PBILLACCT whose subject is the patient. Ovok creates it with the patient's first plan or invoice, and it names the plan's coverage. The caller needs patient_billing_invoices:read.
curl "https://api.sandbox.ovok.com/v1/patient-billing/patients/${PATIENT_ID}/accounts" \
--header "Authorization: Bearer ${OVOK_TOKEN}"The answer is { "items": [ ... ] }. GET /v1/patient-billing/accounts/:accountId returns one account, or 404 ACCOUNT_NOT_FOUND.
{
"id": "a8d3f5c1-2b6e-4719-9c0a-e4f7b1d2635a",
"version": "1",
"patientId": "5f2c9a1e-8d3b-4a7e-b6c4-2e9f1d0a7c38",
"status": "active",
"coverageIds": ["e2c6a9b4-5d17-4f08-a3b1-7c9d0e4f2a56"]
}coverageIds lists the coverages the account bills against, first first.
What Ovok stores
Each patient has one plan Coverage and one billing Account, found by an identifier valued with the patient's id. Invoices are found by your own identifier.
| Record | FHIR resource | Identifier system |
|---|---|---|
| Plan | Coverage of the self-pay type pay, with your plan as its plan class | https://api.ovok.com/fhir/StructureDefinition/patient-billing-plan |
| Billing account | Account of type PBILLACCT | https://api.ovok.com/fhir/StructureDefinition/patient-billing-account |
| Invoice | Invoice on the billing account | The system and value you sent |
The plan's code system sits in the extension https://api.ovok.com/fhir/StructureDefinition/patient-billing-plan-system on the coverage's class. The Patient carries the plan as a tag, so this finds the patients on a plan:
curl --get 'https://api.sandbox.ovok.com/fhir/R4/Patient' \
--data-urlencode '_tag=https://example.com/plans|plus' \
--header "Authorization: Bearer ${OVOK_TOKEN}"The coverage is the record of the plan; the tag is a search convenience.
See also
Last updated on
Insurance
Add, change and remove a patient's health insurance as FHIR Coverage, with the insurer directory, the kinds, the member-number check and the coverage order.
Access
Turn patient billing on for a project, and grant callers the patient_billing_* AccessPolicy rows that let patients and clinic staff read and manage insurance and invoices.