List Appointment Cancellation Reasons¶

Lists the configured reasons (and any threshold-based fee rules) available for Cancel Appointment's reason_key.

Endpoint¶

GET /v2/appointment-cancellation-reasons

Query Parameters¶

Parameter	Type	Required	Description
`page`	integer	Yes	1-based page number. Defaults to `1`.
`page_size`	integer	Yes	Results per page. Defaults to `25`.

Request¶

curl --location '{base_url}/v2/appointment-cancellation-reasons?page=1&page_size=25' \
  --header 'Authorization: Bearer JWT_TOKEN'

Response¶

Success Response¶

Code: 200 OK

{
  "items": [
    {
      "id": "113",
      "reason_key": "SICKNESS",
      "reason_label": "Sickness",
      "reason_type": "PATIENT_REASON",
      "cancellation_fee": 0,
      "fee_criteria": [
        {
          "name": "Less than 24 hr",
          "criteria": "LESS_THAN_24_HOURS",
          "fee": 50
        }
      ]
    }
  ],
  "page": 1,
  "page_size": 25,
  "total": 1,
  "total_pages": 1
}

Response Fields¶

Field	Type	Description
`items`	array of object	The page of results. See Items.
`page`	integer	1-based page number.
`page_size`	integer	Results per page.
`total`	integer	Total results matching the query.
`total_pages`	integer	Total pages available.

Items¶

Field	Type	Description
`id`	string	The cancellation reason id.
`reason_key`	string	Cancellation reason key.
`reason_label`	string	Human-readable label for the reason.
`reason_type`	string or null	Who the reason is attributed to. Open string — only `PATIENT_REASON` and `DOCTOR_REASON` have been observed, against too small a sample to call that exhaustive.
`cancellation_fee`	number	Flat cancellation fee for this reason, when it doesn't use threshold-based `fee_criteria` instead.
`fee_criteria`	array of object	Threshold-based fee rules for this reason (e.g. a bigger fee the closer to the appointment). Empty when the reason uses a flat `cancellation_fee` instead. See Fee Criteria.

Fee Criteria¶

Field	Type	Description
`name`	string	A label for this fee rule.
`criteria`	string	The notice-window threshold this fee rule applies at. Open string — `LESS_THAN_12/24/48_HOURS` are the only ones observed.
`fee`	number	Fee charged at this notice-window threshold.

Error Response¶

Code: 400 Bad Request

{
  "code": "bad_request",
  "message": "Validation failed",
  "errors": [
    {
      "field": "patient_id",
      "message": "must be a string"
    }
  ]
}

Every error has the same shape — a machine-readable code, a message, and an errors[] array that's empty when there's nothing field-specific to report. The HTTP status is authoritative.

Status	`code`	Meaning
`400 Bad Request`	`bad_request`	The request body or parameters failed validation. `errors[]` names the offending fields.
`401 Unauthorized`	`unauthorized`	The access token is missing, malformed or expired.
`403 Forbidden`	`forbidden`	The request references a resource outside the token's organisation or clinic scope.
`404 Not Found`	`not_found`	No such resource, or it's outside your scope.
`429 Too Many Requests`	`rate_limited`	Rate limit exceeded. Back off and retry.
`500 Internal Server Error`	`internal_error`	Unexpected server error.
`502 Bad Gateway`	`upstream_error`	Upstream service failed or timed out.

Notes¶

Read-only. Shared reference data, not clinic-scoped — a reason's identity doesn't depend on which clinic is asking, the same as List Payers.
Retired reasons are omitted; only currently-active ones are listed.