Semantics
Marks the booking cancelled and frees the held slot back into availability. The provider is notified per their notification settings. Refund handling is provider-specific and exposed via the `refund_status` output field.
Invariants
- Idempotent. Cancelling a booking that is already cancelled returns `cancelled: true` with no further side effects.
- If `booking_id` is unknown, returns `error: "unknown_booking"`.
- Once a booking is cancelled, its slot becomes available to subsequent `check_availability` calls.
When to use
When the user has explicitly confirmed they want to cancel. Confirm with the user first because this action is not reversible.
Input schema
{
"type": "object",
"required": [
"booking_id"
],
"properties": {
"reason": {
"type": "string",
"description": "Free-text cancellation reason; surfaced to the provider."
},
"booking_id": {
"type": "string"
},
"agent_vendor": {
"type": "string"
}
},
"additionalProperties": false
}Output schema
{
"type": "object",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean"
},
"error": {
"enum": [
"unknown_booking",
"already_cancelled",
"unauthorized"
],
"type": "string"
},
"cancelled": {
"type": "boolean"
},
"freed_slot": {
"type": "object",
"properties": {
"end_at": {
"type": "string",
"format": "date-time"
},
"start_at": {
"type": "string",
"format": "date-time"
}
}
},
"refund_status": {
"enum": [
"none",
"pending",
"refunded",
"denied"
],
"type": "string"
}
}
}