How bookings work
From availability to confirmation, with the right checks at each step.
A reservation is a sequence, not one click
search_businesses → get_business → check_availability
→ get_quote → create_hold → confirm_booking
→ verify_booking (when required)
→ payment / business approval (when required)
→ confirmedOn 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 |
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.