# Set a patient's plan

Canonical page: https://docs.ovok.com/api/patient-billing/set-a-patient-s-plan

`PUT /v1/patient-billing/patients/{patientId}/plan`

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