Cancel
Cancel an appointment, with or without a refund.
POST /v1/appointments/:appointmentId/cancelA convenience over update-status:
identical behaviour, with status pinned to CANCELLED so a cancellation
cannot be mistyped into something else.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
appointmentId | number | Yes | The numeric appointment id. |
Body
Optional in full — an empty {} cancels with no reason and no refund.
| Field | Type | Required | Description |
|---|---|---|---|
cancellationReason | string | No | Free text, stored against the booking. |
refundIssued | boolean | No | Refund the patient rather than keeping the fee. |
refundPercentage | number | No | 0–100. Required when refundIssued is true. |
refundAmount | number | No | Required when refundIssued is true, and must equal the charge times the percentage. |
refundOverrideReason | string | No | Why this deviates from the clinic's refund policy. |
voidBooking | boolean | No | Void instead of cancel: no notification, no cash refund, excluded from analytics. |
Any status you send is overwritten with CANCELLED.
Try it
/v1/appointments/:appointmentId/cancelPath
Body
POST /v1/appointments//cancel{}https://api.medos.oneUse a dedicated test key, and put your browser's address on its allowlist
A Developer API key authenticates on its own, so it only works from the addresses registered against it — and this page calls from your browser, not your servers. Unless your own public address is on the list you get a 403 naming it, which is the allowlist doing its job. Your browser may also reach us over IPv6 even when your server does not, so the address in the error is often not the one you expected. The key here is kept in memory only and never written to storage, but create a test key for it and deactivate that key when you are done.
Request
curl -sX POST "https://api.medos.one/v1/appointments/9182/cancel" \
-H "x-api-key: $MEDOS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "cancellationReason": "Patient rescheduled by phone" }'Response
The cancelled appointment, in the same shape book-appointment returns.
Common failures
| Status | Cause |
|---|---|
400 | refundIssued: true without a matching refundPercentage and refundAmount. |
400 | The appointment is already in a terminal status. |
404 | No appointment with that id in your workspace. |
Cancel or reschedule?
If the patient wants a different time, reschedule rather than cancelling and rebooking — it keeps the payment state and the booking's history intact, and does not release the fee.