---
title: "Transition appointment status"
method: PUT
path: "/api/appointments/{appointment_id}/status"
tags: ["appointments"]
---

# Transition appointment status

`PUT /api/appointments/{appointment_id}/status`

Change an appointment's status (with an optional note) and run all status side effects.

## Path parameters

- `appointment_id` string, required

## Request body

- UpdateAppointmentStatusRequest — Typed payload for an appointment status transition (with optional note).
  - `status_update` string, required — New appointment status
  - `notes` string, nullable — Optional note saved with the status change
  - `followup_reason` string, nullable — Reason the patient did not book the next meeting, as a FollowupEmailReason value. When set on a transition to FATTO, the matching follow-up email is sent to the patient. An unknown value only skips the email: it never rejects the transition.
  - `followup_reason_text` string, nullable — Free-text reason stored with the follow-up email record when the reason is 'altro'.

## Response `200`

Successful Response

- AppointmentUpdateSuccessResponse — Success response for appointment update endpoints.
  - `success` boolean, required — Operation result
  - `title` string — Success title
  - `message` string, required — Human-readable message
  - `metadata` AppointmentRefundUpdateMetadata — Optional metadata returned when update triggers refund workflow.
    - `appointment_id` string, required — Appointment UUID
    - `refund_request_id` string, nullable — Patient refund request UUID
    - `refund_status` string, nullable — Refund workflow status
    - `credit_note_status` string, nullable — Credit note workflow status

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/corabea/apis/corabea-api.md) · [All operations](https://skmtc.dev/corabea/apis/corabea-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/corabea/corabea-api/revisions/13c1bce1bdc4/schema)