# Record an invoice

Canonical page: https://docs.ovok.com/api/patient-billing/record-an-invoice

`POST /v1/patient-billing/patients/{patientId}/invoices`

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