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:

  1. Look up the Ovok patient id for the payer.
  2. Set the plan with the plan's code and the paid period.
  3. 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 fieldRequiredDescription
plan.systemYesYour code system, a URL such as https://example.com/plans.
plan.codeYesThe plan's code, up to 64 characters.
plan.displayNoThe plan's name for people.
period.startWith periodWhen the paid period began, a date-time with an offset.
period.endNoWhen 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 fieldRequiredDescription
identifierYesYour id for the payment: a system URL and a value of up to 200 characters, without spaces, commas, pipes, backslashes or dollar signs.
statusYesissued, balanced for paid, or cancelled, for example after a refund.
cancelledReasonNoWhy the invoice was cancelled.
issuedAtYesWhen it was issued or paid, a date-time with an offset.
linesYes1 to 50 lines, each with a code (system, code and optional display) naming what was billed, such as the plan.
totalNoThe 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 parameterDescription
limit1 to 100 invoices per page. 30 when left out.
cursorThe 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.

RecordFHIR resourceIdentifier system
PlanCoverage of the self-pay type pay, with your plan as its plan classhttps://api.ovok.com/fhir/StructureDefinition/patient-billing-plan
Billing accountAccount of type PBILLACCThttps://api.ovok.com/fhir/StructureDefinition/patient-billing-account
InvoiceInvoice on the billing accountThe 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

On this page