Booking Lifecycle

First-time workspace setup

Read this concept after Getting Started — Recommended Setup Sequence step 14 Bookings before you rely on list status filters or Timeline for occupancy decisions. Payment vocabulary pairs with setup step 5 Invoicing & Payments. First reservation workflow: Processing a New Booking. Concept pairing: Concepts — Setup sequence after go-live.

Finding your way in this guide

Start with Status Overview and How Status Is Computed, then see Where you see lifecycle in the product. Operational rules: Key Rules. Non-linear operator habits (Lockout catch-up, Pending manual receipt approval, Reject/revert mistaken receipts, Partly collected security deposit, Portfolio segmentation by tenant category, Notification row-click navigation, Payment alert to receivables triage, Confirmation alert triage, Finance debt receivables triage, Finance Income status drill-down, Cash flow forecast drill-down) have matching Related subsections below. Full pairing matrix: Booking Lifecycle section cross-reference · Concepts — Concept cross-reference.

Every booking in Vivin has a computed lifecycle status. The platform does not use a pending booking status, and normal timeline status changes are driven by booking dates plus cancellation state.

Pair with other concepts

Scheduled charges and receipt allocation follow Payment Allocation; tenant contract signing and check-in triggers pair with Tenant Portal (including Portal access by tenant category); channel-imported reservations pair with Integrations & Distribution; booking-scoped external AI clients pair with Tenant MCP. Portfolio operators poll AI usage API (landlord_chat) when AI Chat assists lifecycle triage during Portfolio KPI review. Topic-to-module pairing: Booking Lifecycle section cross-reference. Full pairing matrix: Concepts — Concept cross-reference.

Status Overview

Product Value (`bookingStatus`)	UI Label (where applicable)	Meaning
`upcoming`	Upcoming	Booking start/check-in date is in the future and the booking is not canceled
`current`	Ongoing	Booking is active today (between start/check-in and end/check-out dates)
`ended`	Ended	Booking end/check-out date has already passed
`canceled`	Canceled	Booking was canceled (cancellation type set)

How Status Is Computed

Status is computed in this order:

If the booking has a cancellation type, status is canceled.
Otherwise, if the configured end date is before today, status is ended.
Otherwise, if the configured start date is after today, status is upcoming.
Otherwise, status is current.

Date basis is account-configurable (contract dates or move dates), so "start/end" may come from contract dates or check-in/check-out dates depending on your account settings.

Status Flow

upcoming -> current -> ended
    \         \        \
     \         \        \
      +-------> canceled

Cancellation can be applied from any non-canceled state. Once canceled, status remains canceled.

Where you see lifecycle in the product

The Bookings module uses list filters and tabs that line up with timeline status (for example All versus views that emphasize stays active on today’s date). Row labels and filters reflect upcoming, active stays (often labeled Ongoing in the UI), ended, and canceled, depending on your workspace configuration.

Bookings list — All tab with mixed lifecycle rows

Bookings list — Ongoing tab focusing on stays active today

Bookings list — Upcoming filter with reservations that have not yet started

Bookings list — Ended tab with completed stays

Bookings list — Cancelled tab after explicit cancellation

Walkthrough: on the Bookings list, step through All, Ongoing, Upcoming, Ended, and Cancelled status filters to see how each lifecycle slice narrows the table.

Timeline view

The Timeline layout at /bookings/timeline draws ongoing and upcoming stays as coloured bars per unit (green/teal styling). Ended and canceled reservations are not shown on the chart — use the list view or search when you need those records. Status filter cards still apply, but the Canceled card is disabled on Timeline because those rows are omitted from the Gantt. The chart paginates unit rows on scroll (about 50 listings per batch) and loads booking bars only for listings already visible — see Bookings > Loading unit rows.

Bookings — Timeline view (Day scale) with unit rows and booking bars

Click a bar to open the same booking detail sidebar as on the list; the URL becomes /bookings/timeline/<bookingId> for bookmarking. See Bookings > Timeline view for Week / Month scales, the Only bookings toggle (calendar blocks), and the walkthrough video.

Same-day turnover overlap

When a check-out and check-in share one unit on the same calendar day, paste the unit in toolbar Search and use Week or Month scale to see both bars on one row — or use Sales → Multicalendar for the same Gantt from Sales context. See Glossary — Same-day turnover.

Walkthrough: Timeline view — switch Day / Week / Month, toggle Only bookings, open a booking bar to the detail sidebar, then close.

For column and filter behaviour on the list, see the Bookings module. List and Timeline pairing matrix: Booking Lifecycle section cross-reference.

What Triggers Status Changes

`upcoming` -> `current`

Occurs automatically when the relevant start date is reached.

`current` -> `ended`

Occurs automatically when the relevant end date passes.

Any non-canceled status -> `canceled`

Occurs when a cancellation is processed (sets cancellation type and applies cancellation rules).

Key Rules

Summary

Timeline statuses are computed, not manually advanced. You do not manually set upcoming, current, or ended.
Cancellation is an explicit action. A booking becomes canceled only when the cancellation workflow is executed.
No pending booking status exists in the implemented model.
Payment schedules are created at booking creation. See Payment Allocation for details.
Soft-archive is separate from cancel. Delete Booking removes mistaken stays from default lists without changing the computed timeline status to canceled; Finance → Transactions then hides manual/provider_platform rows for that reservation while keeping vIBAN and credit card rails (#1897). Decision tables: FAQ — Portfolio retirement decisions (building Archive vs Cancel vs Delete) and FAQ — Cancel Booking vs Delete Booking. Ledger triage: FAQ — Manual payments after Delete Booking. See Glossary — Archived booking ledger visibility and Glossary — Archived property.

Booking Lifecycle section cross-reference

Use this table when one lifecycle topic naturally leads into operator configuration, a module view, or a turnover workflow — each row links to the docs you should read before or after the primary status.