# How bookings work

> From availability to confirmation, with the right checks at each step.

Canonical: https://bookwise.live/docs/booking-lifecycle

MCP server version: 1.1.0

## A reservation is a sequence, not one click

### The standard flow

```text
search_businesses → get_business → check_availability
  → get_quote → create_hold → confirm_booking
  → verify_booking (when required)
  → payment / business approval (when required)
  → confirmed
```

On a business-specific endpoint, start with get_business or list_offerings. get_quote is useful before creating a hold, and create_hold also returns a quote. Ask for the customer's agreement to the price, dates and policy before confirming.

## Hold capacity while the customer decides

create_hold reserves an option temporarily and returns holdId, holdToken, expiresAt and the quote. It does not charge or send a message. Keep the hold token for progress checks, code resends and release_hold. Holds expire; a previously available option can be taken before a hold is created.

Multi-room bookings have a parent booking ID and linked allocation rows. Manage the parent ID. Database overlap constraints are the final check against two reservations taking the same resource.

## Follow the next required step

| Status | What happens next |
| --- | --- |
| held | Confirm the agreed details with confirm_booking |
| pending_verification | Customer receives a code; call verify_booking with the code they provide |
| pending_payment | Give the customer the payment URL; the provider callback advances the booking |
| pending_approval | Wait for the business to accept or decline; check progress |
| confirmed | The reservation is confirmed |
| cancelled / expired | Capacity is released; start a new booking if needed |
| completed / no_show | An owner or scheduled workflow has recorded the outcome |

> **Only confirmed means confirmed**: A sent code, payment link or approval request is not a confirmed booking. Follow nextStep and report the actual status to the customer. Never ask for card credentials in chat.

## Change plans without losing context

- get_booking_progress reads an in-progress reservation using a hold token or access token.
- get_booking reads verified booking details using the access token.
- reschedule_booking previews a replacement, then applies the exact accepted option and price. It preserves the original booking if the replacement fails.
- get_cancellation_quote previews fees/refunds; cancel_booking applies the current policy.
- update_booking_details changes this booking's guest name or requests, not its verified contact information.
- recover_booking_access uses a short-lived code to restore access and invalidate the old token.

Rescheduling is for confirmed bookings that have not started. Changes requiring a deposit adjustment, refund, currency change or new business approval must be arranged with the business. Those cases return POLICY_VIOLATION rather than silently changing money or bypassing approval.

## When there is no availability

check_availability can return alternatives. For flexible plans, get_availability_calendar compares dates. With the customer's request, join_booking_waitlist stores a one-time email alert for the requested option. It never reserves capacity or books automatically.

Waiting entries are checked as soon as the business releases capacity (a cancellation, a released hold or a reschedule), and at least once an hour. Entries expire after the requested local date. A notification is an invitation to check again: availability may change before the customer books.