Stay Lifecycle
The booking lifecycle for hospitality reservations.
What is Stay?
Stay tracks a booking through its lifecycle—from initial request to completion. Where retail orders move through placed → shipped → delivered, hospitality bookings move through a different sequence tied to future dates, payments, and physical arrival.
Stay is not a venue description or inventory system. It is a state machine that tracks the journey of a single reservation from availability check through post-stay closure.
Stay does not define how to discover venues or check inventory. It defines what happens after a user decides they want to book something.
Lifecycle Overview
REQUEST → AVAILABLE → HELD → BOOKED → CONFIRMED → BALANCED → ARRIVED → STAYED → COMPLETED
↓ ↓ ↓
MODIFIED CANCELLED NO_SHOW
The lifecycle has two types of states:
Primary States
Sequential progression from request to completion. Each state has clear entry and exit conditions.
Branch States
Modified, cancelled, or no-show. These can occur from multiple points in the primary flow.
Core Concepts
States
Defined lifecycle states with clear triggers and transitions.
Transitions
Valid state changes and what triggers them.
Stay Object
The complete booking record with venue, dates, guests, units, and payment.
Holds
Temporary reservations with configurable expiry before booking commitment.
Modifications
Date changes, room swaps, guest count adjustments with fee handling.
Cancellations
Booking cancellation with policy-based refund calculation.
Webhooks
Event notifications for state changes, holds, and modifications.
Transport Bindings
REST and MCP endpoints for booking operations.
How Agents Use Stays
Check Availability
Agent sends a request with desired dates and unit type. System responds with available or unavailable.
Create Hold (Optional)
If available, agent can request a hold to temporarily reserve inventory while awaiting user confirmation. Holds expire automatically.
Book
Agent converts hold to booked or books directly from available. The booking is created but unpaid.
Confirm Payment
When deposit is captured, stay moves to confirmed. When balance is paid, it moves to balanced.
Track Arrival
Venue records check-in (→ arrived) and check-out (→ stayed). Post-stay processing completes the lifecycle.
Handle Changes
Throughout the lifecycle, agents can handle modification requests, cancellations, and respond to no-show events.
Comparison to Retail Orders
| Retail Order | Hospitality Stay |
|---|---|
| placed | booked |
| payment_pending | booked |
| paid | confirmed / balanced |
| shipped | — |
| delivered | stayed |
| completed | completed |
| cancelled | cancelled |
| refunded | cancelled (with refund) |
Hospitality has no "shipping" phase but adds payment milestones (deposit vs balance) and physical presence tracking (arrived, stayed).
Why Separate Deposit and Balance?
Many hospitality bookings require:
- Deposit at booking time (typically 10-50%)
- Balance before or at arrival
Stay tracks these separately because:
- Refund policies differ based on when cancellation occurs
- Agents need to know if a booking is "secured" vs "fully paid"
- Venues have different balance due timelines