Skip to content

Cancel Appointment

Cancel an existing appointment with specified reason and optional cancellation fee.

Endpoint

POST /apis/v1/appointment/appointment-cancel/{appointment_id}

Path Parameters

Parameter Type Required Description
appointment_id string Yes The unique identifier of the appointment to cancel

Request Body

{
  "cancellation_reason_key": "string",
  "cancellation_reason_label": "string",
  "cancellation_reason_comment": "string",
  "cancellation_fee": number
}

Request Body Parameters

Parameter Type Required Description
cancellation_reason_key string Yes Predefined reason key from the cancellation reasons API (e.g., "CANCELLED_DUE_TO_WEATHER")
cancellation_reason_label string Yes Human-readable reason label for display purposes
cancellation_reason_comment string No Additional comments or notes about the cancellation
cancellation_fee number Yes Cancellation fee amount (use 0 if no fee applies)

Example Request

curl -X POST \
  https://api.example.com/apis/v1/appointment/appointment-cancel/123456 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "cancellation_reason_key": "CANCELLED_DUE_TO_WEATHER",
    "cancellation_reason_label": "Cancelled Due to Weather",
    "cancellation_reason_comment": "Patient called to cancel due to severe weather conditions",
    "cancellation_fee": 0.00
  }'

Getting Cancellation Reasons

Before cancelling an appointment, you need to retrieve the available cancellation reasons using the following API:

Endpoint

GET /apis/v1/appointment/appointment-cancellation

Response

{
  "code": 2000,
  "data": [
    {
      "id": 1,
      "cancellation_fee": 0.0,
      "reason_key": "CANCELLED_DUE_TO_WEATHER",
      "reason_label": "Cancelled Due to Weather",
      "status": null
    },
    {
      "id": 2,
      "cancellation_fee": 25.0,
      "reason_key": "PATIENT_REQUEST",
      "reason_label": "Patient Request",
      "status": null
    },
    {
      "id": 3,
      "cancellation_fee": 50.0,
      "reason_key": "NO_SHOW",
      "reason_label": "No Show",
      "status": null
    }
  ]
}

Usage

  1. First, call the cancellation reasons API to get available reasons
  2. Use the reason_key from the response as cancellation_reason_key in your cancel request
  3. Use the reason_label as cancellation_reason_label
  4. The cancellation_fee from the reasons API should match the fee in your cancel request

Response

Success Response

Status Code: 200 OK

{
  "code": 2000,
  "data": {
    "appointment_id": "123456",
    "status": "cancelled",
    "cancelled_at": "2025-07-17T10:30:00Z",
    "cancellation_reason": {
      "key": "CANCELLED_DUE_TO_WEATHER",
      "label": "Cancelled Due to Weather",
      "comment": "Patient called to cancel due to severe weather conditions"
    },
    "cancellation_fee": 0.00,
    "refund_amount": 75.00
  },
  "message": "Appointment cancelled successfully"
}

Error Responses

Status Code: 400 Bad Request

{
  "code": 4001,
  "message": "Invalid cancellation reason key"
}

Status Code: 404 Not Found

{
  "code": 4041,
  "message": "Appointment not found"
}

Status Code: 409 Conflict

{
  "code": 4091,
  "message": "Appointment is already cancelled"
}

Common Cancellation Reason Keys

The following are examples of cancellation reasons available through the API. Use the GET /apis/v1/appointment/appointment-cancellation endpoint to get the current list of available reasons with their associated fees.

Key Label Typical Fee Description
CANCELLED_DUE_TO_WEATHER Cancelled Due to Weather 0.00 Cancelled due to severe weather conditions
PATIENT_REQUEST Patient Request Variable Patient voluntarily cancelled the appointment
NO_SHOW No Show Higher fee Patient failed to appear without notice
DOCTOR_UNAVAILABLE Doctor Unavailable 0.00 Doctor became unavailable for the scheduled time
EMERGENCY Emergency 0.00 Cancelled due to emergency situation

Important

Always retrieve the current cancellation reasons from the API before implementing cancellation logic, as reasons and fees may be updated by clinic administrators.

Notes

  • Always call GET /apis/v1/appointment/appointment-cancellation first to get available cancellation reasons and fees
  • Use the exact reason_key and reason_label from the cancellation reasons API
  • The cancellation_fee in your request should match the fee specified in the reasons API
  • Once an appointment is cancelled, it cannot be uncancelled through this endpoint
  • Cancellation fees are applied based on the clinic's policy and the selected reason
  • The refund amount is calculated automatically based on the original payment and cancellation fee
  • Cancelled appointments will trigger webhook notifications if configured
  • The appointment status will be permanently changed to "cancelled"