Update appointment status

Move an appointment through its lifecycle — confirmed, completed, no-show, cancelled.

PATCH /v1/appointments/:appointmentId/status

The general status write. Cancellation has its own convenience route that pins the status for you, but everything it does can be done here.

Path parameters

Name	Type	Required	Description
`appointmentId`	number	Yes	The numeric appointment id.

Body

Field	Type	Required	Description
`status`	string	Yes	The new status. See the table below.
`cancellationReason`	string	No	Free text. Meaningful only with `CANCELLED`.
`refundIssued`	boolean	No	With `CANCELLED` on a paid appointment: `true` refunds the patient (`paymentStatus` becomes `REFUNDED`), `false` keeps 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 you deviated from the clinic's refund policy default.
`voidBooking`	boolean	No	With `CANCELLED`: void the booking entirely — no patient notification, no cash refund, excluded from analytics. For a pack-funded visit, `refundIssued` then decides whether the session credit returns to the wallet.

Statuses

Value	Meaning
`SCHEDULED`	Booked, not yet confirmed.
`CONFIRMED`	The patient confirmed they are coming.
`IN_CONSULTATION`	With the doctor now.
`COMPLETED`	Seen. Terminal.
`NO_SHOW`	Did not turn up.
`CANCELLED`	Called off. Terminal.
`RESCHEDULED`	Set by reschedule; you do not normally write it.
`OVERDUE`, `MISSED`	Derived states Medos maintains.

Medos enforces the transitions — an appointment already COMPLETED or CANCELLED will not move again.

Try it

PATCH/v1/appointments/:appointmentId/status

API key*

Sent as x-api-key. Shared by every Try block on this page.

Path

Appointment ID*

Body

Status*The target status. Upstream rejects a transition it does not allow.

Request

PATCH /v1/appointments//status

{
  "status": "CHECKED_IN"
}

to https://api.medos.one

Use 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 PATCH "https://api.medos.one/v1/appointments/9182/status" \
  -H "x-api-key: $MEDOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "COMPLETED" }'

Cancelling a paid visit with a half refund:

curl -sX PATCH "https://api.medos.one/v1/appointments/9182/status" \
  -H "x-api-key: $MEDOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "CANCELLED",
    "cancellationReason": "Patient travelling",
    "refundIssued": true,
    "refundPercentage": 50,
    "refundAmount": 250
  }'

Response

The updated appointment, in the same shape book-appointment returns — including the refundPercentage, refundAmount and refundOverrideReason fields once a refund has been issued.

Common failures

Status	Cause
`400`	`refundIssued: true` without `refundPercentage` and `refundAmount`, or with an amount that does not match the percentage.
`400`	A transition Medos does not allow from the current status.
`404`	No appointment with that id in your workspace.

Refunds move real money

refundIssued: true instructs Medos to refund the patient. Send it only when the clinic has decided to — not as a default on every cancellation.

Update status

Path parameters

Body

Statuses

Try it

Request

Response

Common failures

On this page