---
title: "Cancel a booking or request"
method: POST
path: "/v1/bookings/{booking_id}/cancel"
tags: ["Bookings"]
---

# Cancel a booking or request

`POST /v1/bookings/{booking_id}/cancel`

## Request

- Base URL: `https://threshold.rentals/api`
- URL: `https://threshold.rentals/api/v1/bookings/{booking_id}/cancel`
- Auth: HTTP bearer

Cancel for the guest after they agreed to the refund from previewCancellation. Pass that refund as expected_refund; if it has changed, you get 409 refund_changed and nothing is cancelled. Not possible once the stay has started.

## Path parameters

- `booking_id` string, required

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `expected_refund` object, required
    - `amount` integer, required: refund.amount from previewCancellation, in cents.
    - `currency` string

## Response `200`

The cancelled booking

- Booking
  - `id` string
  - `confirmation_code` string
  - `status` 'awaiting_payment' | 'pending_host_confirmation' | 'confirmed' | 'declined' | 'expired' | 'cancelled_by_guest' | 'cancelled_by_host' | 'cancelled_unpaid'
  - `property_id` string
  - `check_in` string, date
  - `check_out` string, date
  - `party` Party
    - `adults` integer
    - `children` integer
    - `infants` integer
    - `pets` integer
    - `service_animals` integer
  - `total` Money
    - `amount` integer, required: In cents
    - `currency` string, required
  - `amount_paid` Money
    - `amount` integer, required: In cents
    - `currency` string, required
  - `amount_refunded` Money
    - `amount` integer, required: In cents
    - `currency` string, required
  - `refund_schedule` RefundTier[]
    - `until` string, date-time: Cancel before this time…
    - `refund` Money
      - `amount` integer, required: In cents
      - `currency` string, required
  - `payment` object
    - `collected_by` 'threshold' | 'host'
    - `status` string
    - `plan` string
    - `payment_url` string, uri: Present when the guest still has to pay
    - `charge_date` string, date-time
    - `pay_by` string, date-time
  - `host_confirm_by` string, date-time
  - `arrival_info_available_at` string, date-time
  - `arrival_info_sent_at` string, date-time
  - `special_requests` string
  - `host_message` string
  - `created_at` string, date-time

## Other responses

- `400`: Invalid input (e.g. invalid_dates, unknown_amenity, place_not_found)
- `401`: Agent token missing (unauthorized)
- `404`: Not found (property_not_found, quote_not_found, booking_not_found)
- `409`: Conflict (dates_unavailable with alternatives, quote_converted, refund_changed, not_cancellable, stay_started)
- `429`: Rate limited or too many open requests: see Retry-After

---

[API](https://skmtc.dev/threshold/apis/threshold-stays-api.md) · [All operations](https://skmtc.dev/threshold/apis/threshold-stays-api/llms.txt) · [OpenAPI document](https://skmtc.dev/threshold/apis/threshold-stays-api/revisions/7acf3ae91b56?raw)