Patient billing

List a patient's invoices

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

Lists the patient's invoices, latest first, a page at a time.

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.
  • limit is 1 to 100 (30 when left out). Send nextCursor back as cursor for the next page; a cursor no page gave answers 400 PATIENT_BILLING_CURSOR_INVALID.

Example

curl 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/invoices?limit=30' \  -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}$

Query Parameters

cursor?string

nextCursor from the previous page.

Length1 <= length <= 4000
limit?integer
Range1 <= value <= 100
Default30

Response Body

The patient's invoices, latest first.

application/json
  1. response
items*array<>
nextCursor*string
Example Request
curl -X GET 'https://api.sandbox.ovok.com/v1/patient-billing/patients/string/invoices'
Example Response
{  "items": [    {      "id": "string",      "version": "string",      "patientId": "string",      "identifier": {        "system": "string",        "value": "string"      },      "status": "string",      "cancelledReason": "string",      "issuedAt": "string",      "accountId": "string",      "clinicId": "string",      "lines": [        {          "code": {            "system": "string",            "code": "string",            "display": "string"          },          "chargeId": "string",          "amount": {            "value": 0,            "currency": "string"          }        }      ],      "total": {        "value": 0,        "currency": "string"      }    }  ],  "nextCursor": "string"}

Get a billing account GET

Gets one billing account. **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 account's patient. An account you cannot see answers **404** `ACCOUNT_NOT_FOUND`. ## Example ```bash curl 'https://api.sandbox.ovok.com/v1/patient-billing/accounts/<accountId>' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```

Record an invoice POST

Records an invoice for a paid period, from your server's payment or store webhooks. The invoice is a FHIR `Invoice` on the patient's billing account, which Ovok makes if it is missing. **Scope:** a project admin or an admin ClientApplication, in a project with `PATIENT_BILLING_ENABLED` on. Anyone else: **403** `PATIENT_BILLING_NOT_ALLOWED`. ## Behaviour - `identifier` is your id for the payment, such as your payment provider's. The same identifier for the same patient again is the same invoice: it answers **200** and is written over when it changed, so a retried webhook never records it twice. - A new identifier answers **201** with `Location: /v1/patient-billing/invoices/<id>`. - `status` is `issued`, `balanced` (paid) or `cancelled`, for example after a refund, with `cancelledReason`. - `lines` say what was billed, such as the plan paid for; `total` is the gross amount. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/invoices' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "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" } }' ```