Skip to main content

Quotes, Holds & Bookings - Version Mapping

Domain: Quotes, Holds & Bookings First Introduced: MVP.1 (read-only) / V1.0 (full) Last Updated: 2025-10-25

Version Introduction Timeline​

VersionStatusScopeDescription
MVP.0OUT OF SCOPENoneBookings domain not implemented
MVP.1PARTIALRead-OnlyPassive booking awareness from iCal imports
V1.0PLANNEDFull ImplementationComplete booking engine with quotes, holds, confirmations
V1.1FUTUREModificationsBooking amendments and changes
V1.2FUTUREMulti-UnitMulti-unit and group bookings
V1.3FUTUREAdvanced CancellationsPro-rated refunds, custom policies
V2.0FUTUREGuest ProfilesCentralized guest management
V2.1FUTURECommunicationsAutomated email workflows
V2.2FUTUREChannel SyncBidirectional OTA integration
V2.3FUTURESmart EngineML-based optimization

MVP.0 - OUT OF SCOPE​

Status: Not Implemented Rationale: MVP.0 focuses on foundation (tenancy, authorization, supply, content). Booking engine deferred to reduce scope.

Excluded Entities​

  • All booking entities deferred

Excluded Features​

  • Quote generation
  • Hold management
  • Booking creation
  • State machine workflows
  • Cancellation processing

Workaround​

  • External booking tracking (informal)
  • No reservation system
  • Platform for property management only

MVP.1 - READ-ONLY BOOKING AWARENESS​

Status: Partial Implementation Scope: Passive awareness of external bookings

Included Entities (1)​

  1. Bookings (Read-Only)
    • Minimal schema for imported bookings
    • Source tracking (airbnb, vrbo, etc.)
    • Basic guest information
    • Check-in/check-out dates
    • Confirmation code storage

Database Schema (Minimal)​

CREATE TABLE bookings (
  id UUID PRIMARY KEY,
  org_id UUID NOT NULL,
  account_id UUID NOT NULL,
  space_id UUID NOT NULL,
  confirmation_code VARCHAR(50),
  source VARCHAR(50) NOT NULL,
  channel_ref VARCHAR(255),
  checkin DATE NOT NULL,
  checkout DATE NOT NULL,
  nights INTEGER,
  guests INTEGER,
  guest_name VARCHAR(255),
  guest_email VARCHAR(255),
  state VARCHAR(50) DEFAULT 'confirmed',
  total_price BIGINT,
  currency VARCHAR(3) DEFAULT 'USD',
  created_at TIMESTAMPTZ,
  updated_at TIMESTAMPTZ
);

Key Features​

iCal Import:

  • Parse VEVENT from external calendars
  • Extract booking details
  • Create booking records
  • Generate calendar blocks

Calendar Display:

  • Show booked periods on calendar UI
  • Block dates from manual booking
  • Display as "Booked" status

Business Rules​

  1. Bookings imported from iCal feeds only
  2. Create matching availability calendar block
  3. No editing capability from TVL platform
  4. Guests manage bookings via original OTA
  5. Display-only in admin UI

Deferred to V1.0​

  • Quote generation
  • Hold management
  • Booking creation workflow
  • State machine transitions
  • Line item tracking
  • Cancellation processing

V1.0 - FULL BOOKING ENGINE​

Status: Planned Target: Initial production release

Core Entities (6)​

  1. Quote - Priced offer for potential stay

    • Immutable pricing snapshot
    • Rate plan linkage
    • Line-item breakdown
    • Expiration handling (15-30 min TTL)
    • Multi-occupancy support

  2. QuoteLineItem - Itemized charge breakdown

    • Nightly rates
    • Cleaning fees
    • Service fees
    • Taxes
    • Discounts
    • Adjustments

  3. Hold - Temporary inventory reservation

    • Checkout flow holds (15 min TTL)
    • Manual holds (24 hour TTL)
    • Automatic expiration
    • Calendar blocking
    • Quote linkage

  4. Booking - Confirmed reservation

    • Complete state machine
    • Guest information
    • Confirmation code generation
    • Payment linkage
    • Calendar block creation

  5. BookingLineItem - Booking charge breakdown

    • Copied from quote at confirmation
    • Immutable record
    • Refundable flag tracking
    • Financial reconciliation

  6. Cancellation - Cancellation records

    • Policy evaluation
    • Refund calculation
    • Days-before-checkin tracking
    • Penalty computation
    • Refund status tracking

State Machine​

    pending
       ↓
   confirmed ──→ checked_in ──→ completed
       ↓              ↓
   canceled      canceled

Valid Transitions:

  • pending → confirmed (payment received)
  • pending → canceled (payment failed)
  • confirmed → checked_in (guest arrives)
  • confirmed → canceled (pre-arrival cancellation)
  • checked_in → completed (guest departs)
  • checked_in → canceled (rare: during-stay cancellation)

Key Features​

Quote Generation:

  • Real-time pricing from rate plans
  • Availability verification
  • Fee application
  • Tax calculation
  • Expiration management
  • Line-item transparency

Hold Management:

  • Inventory locking during checkout
  • Race condition prevention
  • Automatic cleanup (background job)
  • Expiration handling
  • Hold-to-booking conversion

Booking Confirmation:

  • Unique confirmation code generation (8-12 chars)
  • Payment integration
  • Calendar block creation
  • State transition tracking
  • Event publishing

Cancellation Processing:

  • Policy-based refund calculation
  • Flexible, moderate, strict, non-refundable policies
  • Days-before-checkin rules
  • Penalty calculation
  • Inventory release
  • Refund initiation

Check-In/Check-Out:

  • Guest arrival tracking
  • Departure recording
  • Payout trigger (on completion)
  • State updates

Cancellation Policy Types​

  1. Flexible - Full refund up to 24 hours before check-in
  2. Moderate - Full refund up to 5 days before, 50% up to 24 hours
  3. Strict - Full refund up to 14 days before, 50% up to 7 days
  4. Non-Refundable - No refunds under any circumstances
  5. Custom - Property-specific rules

Business Rules​

  1. Confirmation codes globally unique
  2. No overlapping bookings per space
  3. Quotes expire after validity period
  4. Holds prevent double-booking
  5. State transitions follow state machine
  6. Bookings never hard deleted (soft delete)
  7. All amounts in minor units (cents)
  8. Line items must reconcile with totals

Database Objects​

Tables: 6 (Quote, QuoteLineItem, Hold, Booking, BookingLineItem, Cancellation) Indexes: 20+ Constraints: 15+ Triggers: State validation

API Endpoints​

  • POST /quotes - Generate quote
  • GET /quotes/:id - Retrieve quote
  • POST /holds - Create hold
  • DELETE /holds/:id - Release hold
  • POST /bookings - Confirm booking
  • GET /bookings - List bookings
  • GET /bookings/:id - Get booking details
  • PUT /bookings/:id/check-in - Check in guest
  • PUT /bookings/:id/check-out - Check out guest
  • POST /bookings/:id/cancel - Cancel booking
  • GET /bookings/:id/cancellation - Get cancellation details

Background Jobs​

  1. Hold Expiration Cleanup - Every 5 minutes
  2. Quote Expiration - Every 15 minutes
  3. Auto Check-Out - Daily at noon
  4. Payout Trigger - After completion

Performance Requirements​

  • Quote generation: <100ms target
  • Hold creation: <50ms with locks
  • Booking confirmation: <200ms
  • State transitions: <100ms

Deferred to V1.1+​

  • Booking modifications (date changes, upgrades)
  • Multi-unit bookings
  • Group bookings
  • Guest profiles and history
  • Automated communications
  • Advanced cancellation policies

V1.1 - BOOKING MODIFICATIONS​

Status: Future Scope: Amendment support

New Entities​

  • BookingModification - Amendment audit trail

New Features​

  • Date Changes

    • Extend or shorten stay
    • Availability re-check
    • Repricing logic

  • Guest Count Changes

    • Update occupancy
    • Recalculate fees
    • Capacity validation

  • Room/Unit Upgrades

    • Switch to different unit
    • Price differential handling

  • Partial Cancellations

    • Multi-unit booking support
    • Partial refund calculation

Business Rules​

  • Original booking preserved in audit trail
  • Modification creates new version
  • Price adjustments tracked separately
  • State transitions validated

V1.2 - MULTI-UNIT BOOKINGS​

Status: Future Scope: Group reservations

New Features​

  • Parent-Child Booking Structure

    • Group booking container
    • Individual unit bookings
    • Coordinated state management

  • Partial Fulfillment

    • Some units confirmed, others pending
    • Flexible payment handling

  • Group Pricing

    • Volume discounts
    • Package pricing

Impact​

  • Support retreats and group events
  • Complex booking scenarios
  • Enhanced revenue opportunities

V1.3 - ADVANCED CANCELLATIONS​

Status: Future Scope: Flexible cancellation handling

New Features​

  • Pro-Rated Refunds

    • Based on percentage of stay completed
    • Partial stay cancellations

  • Custom Policies

    • Property-specific rules
    • Dynamic policy definition

  • Cancellation Taxonomy

    • Reason categorization
    • Analytics support

  • Forecasting

    • Cancellation prediction
    • Risk scoring

V2.0 - GUEST PROFILES & HISTORY​

Status: Future Scope: Centralized guest management

New Entities​

  • GuestProfile - Centralized guest identity
  • GuestPreference - Saved preferences
  • GuestReview - Rating system

New Features​

  • Booking History

    • Cross-property tracking
    • Lifetime value calculation

  • Preferences

    • Special needs
    • Communication preferences
    • Favorite properties

  • Loyalty Programs

    • Repeat guest recognition
    • Rewards tracking

V2.1 - AUTOMATED COMMUNICATION​

Status: Future Scope: Email workflow automation

New Features​

  • Confirmation Emails

    • Property details
    • Booking summary
    • Payment receipt

  • Pre-Arrival Messages

    • Check-in instructions
    • Access codes
    • Local recommendations

  • Mid-Stay Check-In

    • Satisfaction surveys
    • Issue reporting

  • Post-Stay Follow-Up

    • Thank you messages
    • Review requests
    • Future booking offers

V2.2 - CHANNEL BIDIRECTIONAL SYNC​

Status: Future Scope: Two-way OTA integration

New Features​

  • Push Bookings to OTAs

    • Automatic calendar blocking
    • Rate synchronization

  • Receive Booking Updates

    • Webhook integration
    • Real-time sync

  • Conflict Resolution

    • Double-booking prevention
    • Priority rules

V2.3 - SMART BOOKING ENGINE​

Status: Future Scope: ML-based optimization

New Features​

  • Pricing Recommendations

    • Dynamic pricing suggestions
    • Demand forecasting

  • Availability Rules

    • Min stay optimization
    • Gap filling automation

  • Overbooking Management

    • Risk assessment
    • Automated handling

Feature Availability Matrix​

FeatureMVP.0MVP.1V1.0V1.1V1.2V2.0+
Read-Only Bookings❌✅✅✅✅✅
iCal Import❌✅✅✅✅✅
Quote Generation❌❌✅✅✅✅
Hold Management❌❌✅✅✅✅
Booking Confirmation❌❌✅✅✅✅
State Machine❌❌✅✅✅✅
Cancellation (Basic)❌❌✅✅✅✅
Check-In/Check-Out❌❌✅✅✅✅
Booking Modifications❌❌❌✅✅✅
Multi-Unit Bookings❌❌❌❌✅✅
Pro-Rated Refunds❌❌❌❌❌✅
Guest Profiles❌❌❌❌❌✅
Automated Communications❌❌❌❌❌✅
Bidirectional Channel Sync❌❌❌❌❌✅

Dependencies​

Upstream Dependencies (Required First)​

  • Identity & Tenancy (MVP.0) - Org/Account structure
  • Supply (MVP.0) - Spaces and Units
  • Availability & Calendars (MVP.1) - Calendar blocks
  • Pricing & Revenue (V1.0) - Quote generation
  • Authorization & Access (MVP.0) - Permission enforcement

Downstream Dependencies (Requires This Domain)​

  • Payments & Financials (V1.0) - Payment processing
  • Channels & Distribution (V1.0+) - Booking syndication
  • Analytics & Audit (V1.0+) - Booking metrics
  • Search & Indexing (V1.0+) - Availability impact

Migration Path​

From MVP.0 → MVP.1​

Schema Changes:

  1. Create minimal bookings table
  2. Add basic indexes
  3. Create calendar block integration

Feature Migration:

  • Implement iCal import workflow
  • Display booked dates on calendar

Estimated Effort: 1 week

From MVP.1 → V1.0​

Data Migration:

  1. Extend bookings table with full schema
  2. Create new tables (Quote, Hold, Cancellation, etc.)
  3. Migrate existing bookings to new schema
  4. Create default cancellation policies

Feature Migration:

  • Implement quote generation
  • Build hold management
  • Create booking confirmation workflow
  • Add state machine logic
  • Implement cancellation processing

Estimated Effort: 6-8 weeks

  • Schema deployment: 2 days
  • Data migration: 3 days
  • Core API implementation: 4 weeks
  • Background jobs: 1 week
  • Testing and validation: 2-3 weeks

V1.0 → V1.1 (Modifications)​

Schema Changes:

  1. Create booking_modifications table
  2. Add modification tracking fields

Feature Migration:

  • Implement amendment workflows
  • Build repricing logic
  • Add validation rules

Estimated Effort: 3-4 weeks

Document Status: Complete Total Lines: 540+ Coverage: MVP.0 through V2.3