# Retrieving and cancelling a booking

With these endpoints your client can show a confirmed booking and cancel it.
Cliento's own "manage booking" page uses the same endpoints. That is the page
linked from Cliento's confirmation email and SMS.

> **Note**
>
> Unlike the rest of the API, these endpoints are **not** under the account
> [base URL](https://developers.cliento.com/docs/widget-api.md#base-url). The `{ref}` in the URL alone identifies both
> the account and the booking:
>
> ```
> https://apibk.cliento.com/api/v2/booking/{ref}
> ```

<a id="the-booking-ref"></a>

## The `{ref}` in the URL

The `{ref}` in the URL is the `cbUuid` from the
[reserve and confirm](https://developers.cliento.com/docs/widget-api/booking.md) responses, encoded as Base64. This is
the same format Cliento's own confirmation links use. It is not `cbRef`, the
short reference shown to the customer.

```bash
echo -n "4674c65b-a64f-43a5-94c7-af3b59053cc6" | base64
# NDY3NGM2NWItYTY0Zi00M2E1LTk0YzctYWYzYjU5MDUzY2M2
```

Store the `cbUuid` if your client needs to manage bookings later. No other
identifier is supported.

The ref is the only credential: anyone with the ref can view and cancel the
booking, just like anyone with the confirmation email can. Treat it like a
secret and never expose refs of other customers' bookings.

## Retrieve a booking

```
GET https://apibk.cliento.com/api/v2/booking/{ref}
```

Returns the booking, with a flag for whether it is cancelled. The response also
has the account settings needed to render a manage-booking page.

**Response 200**

```json
{
  "created": "2026-10-23T11:41:24+02:00",
  "date": "2026-10-30",
  "time": "09:00:00",
  "resource": "",
  "customer": "Test Testsson",
  "phoneNumber": "+46701234567",
  "customerEmail": "test@example.com",
  "cancelled": false,
  "services": [
    { "id": 68811, "name": "Women's haircut", "price": 595.0, "priceFrom": false, "duration": 45 }
  ],
  "payment": null,
  "prefs": { "...": "same preference object as in settings, shortened here" }
}
```

| Field | Description |
| --- | --- |
| `created` | When the booking was made, in the account's time zone |
| `date`, `time` | Start of the booking, in the account's time zone |
| `resource` | Public name of the booked resource, may be empty |
| `customer`, `phoneNumber`, `customerEmail` | The customer details from the booking |
| `cancelled` | `true` when the booking is cancelled |
| `services` | The booked services, same shape as in the reserve response |
| `payment` | The online payment, or `null` when the booking was not paid online |
| `prefs` | The account preferences, see [settings](https://developers.cliento.com/docs/widget-api/reference-data.md#fetch-settings) |

When the booking was paid online, `payment` has these fields, among others:
`paymentProvider`, `paymentStatus`, `amount`, `refundedAmount`,
`transactionDate` and `refundDate`. `refundDate` is `null` until a refund is
made. See [Payments](https://developers.cliento.com/docs/widget-api/payments.md).

The `prefs` object tells you whether cancellation is possible:

| Preference | Meaning |
| --- | --- |
| `web_allowCancellation` | The account allows customers to cancel online |
| `web_cancelUpToMinutes` | Cancellation closes this many minutes before the booking starts |

The cancellation deadline is the booking start time minus
`web_cancelUpToMinutes`. Use it to decide whether to show a cancel button, and
to explain why cancellation is closed. Check `cancelled` as well: a
cancelled booking cannot be cancelled again.

**Errors**

| Status | When |
| --- | --- |
| 404 | The ref does not match a booking, or the account no longer exists |

A malformed ref can also produce other error statuses. Treat every non-`200`
response as "booking not available" rather than branching on the exact status.

## Cancel a booking

```
DELETE https://apibk.cliento.com/api/v2/booking/{ref}
```

Cancels the booking. Cliento sends cancellation notifications to the customer
according to the account settings. A booking that was paid online with a
completed payment is refunded automatically. How long the refund takes depends
on the payment provider: Swish refunds are immediate, card refunds take a few
days.

**Response 204**

No body. Cancelling an already cancelled booking is also `204`, without
repeating notifications or refunds, so the call is safe to retry.

**Errors**

| Status | When |
| --- | --- |
| 403 | Cancellation is not allowed: the account has online cancellation off, or the cancellation deadline has passed |
| 404 | The ref does not match a booking, or the account no longer exists |

After a successful cancellation the slot opens up for other customers.
Retrieving the booking again returns it with `"cancelled": true`.

## Rescheduling

There is no reschedule endpoint. To move a booking, cancel it and create a new
booking through the regular [booking flow](https://developers.cliento.com/docs/widget-api/booking-flow.md). Note that the
cancellation policy applies: past the cancellation deadline the booking cannot
be moved either.