List all cancellation reasons

GET /api/configuration/cancellation-reasons

Success: 200 OK

Products: Operator (FOH)
Features: Front of House Generic Access (FOHGENERIC)

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 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.

Sample request

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

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.

This page as markdown · All pages · llms.txt