# List all cancellation reasons

`GET /api/configuration/cancellation-reasons`

- **Success:** `200 OK`
- **Products:** Operator (`FOH`)
- **Features:** Front of House Generic Access (`FOHGENERIC`)

HTML version: [List all cancellation reasons](https://support.gladstonesoftware.cloud/reference/configuration/list-all-cancellation-reasons)

## Overview

Returns the operator's list of reasons a booking may be cancelled — the picklist a member of staff
chooses from when they cancel something, and the picklist your integration must present if it
cancels on their behalf.

You need this before you can cancel. Endpoints that cancel bookings take a numeric cancellation
reason id rather than free text, and reject an id that is not on this list, so fetch it once at
start-up and cache it. [Delete linked reservations from a block booking
schedule](../bookings/deletes-all-linked-reservations-from-a-block-booking-schedule.md) is the
clearest example: its `cancellationReasonCodeId` is checked against exactly the same rule this
endpoint applies, and a mismatch fails the whole cancellation with a `400`.

The list is operator-configured, not a fixed platform enumeration. It varies between tenants, it
can be added to, and entries can be retired — so do not hard-code ids, and do not assume a reason
you saw in one environment exists in another. Only reasons that are currently **active** are
returned, and only reasons of the cancellation kind: the operator's reason codes cover
other purposes too, and this endpoint filters them out. A reason the operator retires disappears
from this list but remains attached to the historic records that used it, so if you display a
stored reason id you may find no matching entry here — render the id or your own stored label
rather than treating it as an error.

There are no parameters and no filtering. The response is always an array; a tenant that has
configured no cancellation reasons gets `[]` rather than an error, which is worth handling because
it means no cancellation your integration attempts can succeed until the operator configures one.

A reason added or retired by the operator may take a short
while to appear or disappear here.

## Endpoint

`GET {base_url}/api/configuration/cancellation-reasons`

`{base_url}` is the environment URL issued to your integration. See [Authenticating with Gladstone APIs](../../guides/authenticating-with-gladstone-apis.md).

## Sample request

```bash title="cURL"
curl -X GET '{base_url}/api/configuration/cancellation-reasons' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true'
```

## Response fields

| Field | Type | Description |
|-------|------|-------------|
| `[].id` | integer (int32) | The value to send wherever a cancellation reason is required, such as `cancellationReasonCodeId` on the block booking deletion endpoints. It is an integer generated per tenant, so **the same reason has different ids in different environments** — resolve it by `name` at start-up rather than baking the number into your code. Store it against your own cancellation records if you need to report on why something was cancelled. |
| `[].name` | string | The short label for the reason, up to 50 characters and never empty — this is what you show in a picker. It is the only stable thing to match on if you need to find a particular reason programmatically, and reason names are unique enough in practice to be used that way, though uniqueness is not enforced, so handle the possibility of two entries sharing a name. |
| `[].description` | string | A longer explanation of when the reason applies, up to 100 characters. It is optional and is `null` where the operator did not supply one, so fall back to `name` rather than rendering an empty entry. |

## Sample response

```json title="200 OK"
[
  {
    "id": 3,
    "name": "Facility unavailable",
    "description": "Cancelled by the centre because the facility could not be used"
  },
  {
    "id": 7,
    "name": "Customer request",
    "description": null
  }
]
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `500` | Internal server error | An unexpected server-side failure while reading the reason list. The body is empty. Note what is **not** here: there is no `404`. A tenant with no cancellation reasons configured returns `200` with an empty array, so an empty list is a configuration state to handle in your UI, not an error to retry. |