> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seyaha.net/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /bookings/{externalBookingId}/cancel

> Cancel a confirmed booking. Seyaha calls this when a paid booking is cancelled.

Seyaha calls `POST /bookings/{externalBookingId}/cancel` when a confirmed, paid booking
is cancelled by the customer or a Seyaha operator.

The `externalBookingId` path parameter is the value you returned in `externalBookingId`
from `POST /bookings/confirm`.

<Note>
  This endpoint is optional. If you don't implement it, cancellations on Seyaha will
  not propagate to your platform. You would need to handle the reconciliation manually
  or via a separate notification channel.
</Note>

***

## Request

```http theme={null}
POST /bookings/{externalBookingId}/cancel
Authorization: Bearer <auth_key>
Content-Type: application/json
```

### Path parameter

| Parameter           | Description                                                         |
| ------------------- | ------------------------------------------------------------------- |
| `externalBookingId` | The `externalBookingId` from your `POST /bookings/confirm` response |

### Request body (optional)

```json theme={null}
{
  "externalBookingId": "BK-2026-9999",
  "reason": "Customer requested cancellation"
}
```

| Field               | Type   | Description                                 |
| ------------------- | ------ | ------------------------------------------- |
| `externalBookingId` | string | Echo of the path parameter, for convenience |
| `reason`            | string | Optional cancellation reason                |

***

## Response

```http theme={null}
200 OK
Content-Type: application/json

{
  "success": true,
  "message": "Booking cancelled"
}
```

### Response body

| Field     | Type    | Description                         |
| --------- | ------- | ----------------------------------- |
| `success` | boolean | `true` if the booking was cancelled |
| `message` | string  | Optional status message             |

***

## Full flow example

```
1. Booking was created:
   POST /bookings/reserve → HOLD-2026-0001
   POST /bookings/confirm → externalBookingId: "BK-2026-9999"

2. Customer or operator cancels the booking on Seyaha

3. Seyaha calls:
   POST /bookings/BK-2026-9999/cancel
   { "reason": "Customer requested cancellation" }

4. Your API processes the cancellation and responds:
   { "success": true }

5. Restore slot availability and process any refund on your side
```

***

## Implementation notes

<Warning>
  Cancellation does not automatically process a refund via Seyaha's payment system.
  Seyaha handles refunds on its side independently. On your side, cancel the booking
  and restore slot availability — do not attempt to charge or refund through this call.
</Warning>

* Timeout: **10 seconds**
* Restore the slot's vacancies so other customers can book the freed spot.
* If the booking ID does not exist on your side, return `200` with `success: true` — Seyaha has already cancelled it internally.
* Implement idempotency — multiple cancel calls for the same booking should always return `200`.