Skip to main content

Booking Lifecycle

Ask AI Chat “Where do I open Bookings list status tabs to filter reservations by lifecycle — Upcoming, Ongoing, Ended, and Canceled (not Sales Multicalendar, and not Timeline-only)? Name the Portfolio Bookings list filters — product navigation only, no account data.” — then open Portfolio → Bookings list filters (ai-chat-product-context-booking-lifecycle-reply.png, ai-chat-product-context-booking-lifecycle-flow.mp4). The assistant typically says Bookings → List view with Upcoming, Ongoing (may say Current), Ended, and Canceled. Same grounding external MCP clients get from get-vivin-context-bookings-tenants. Distinct from Sales → Multicalendar and from Timeline-only charts.

AI Assistant — where to open Bookings list status tabs for lifecycle filters

Walkthrough: ask AI Assistant where to open Bookings list lifecycle status filters, then open Portfolio → Bookings list view tabs.
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. Habit-specific shortcuts live under Related below.

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.

Status Overview​

Product Value (bookingStatus)UI Label (where applicable)Meaning
upcomingUpcomingBooking start/check-in date is in the future and the booking is not canceled
currentOngoingBooking is active today (between start/check-in and end/check-out dates)
endedEndedBooking end/check-out date has already passed
canceledCanceledBooking was canceled (cancellation type set)

How Status Is Computed​

Status is computed in this order:

  1. If the booking has a cancellation type, status is canceled.
  2. Otherwise, if the configured end date is before today, status is ended.
  3. Otherwise, if the configured start date is after today, status is upcoming.
  4. 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. After Create Booking, Delete Booking, or Cancel booking, stay bars on units already on the chart update without a reload — see Stay bars update after create or delete. When Only bookings is on, the unit list updates in place as well — see Unit list updates after create or delete.

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
  1. Timeline statuses are computed, not manually advanced. You do not manually set upcoming, current, or ended.
  2. Cancellation is an explicit action. A booking becomes canceled only when the cancellation workflow is executed.
  3. No pending booking status exists in the implemented model.
  4. Payment schedules are created at booking creation. See Payment Allocation for details.
  5. 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. 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 the sections above for this concept. Related module and workflow pages are linked inline where they help the next step.

Pair with other Booking Lifecycle guide sections

Related below links this concept to modules, workflows, settings, and escalation paths.

Documentation map & escalation​

  • Introduction — Platform overview and how documentation sections connect
  • Getting Started — Recommended setup sequence before you rely on list filters and Timeline
  • Concepts — Underlying models behind computed statuses and cancellation
  • Modules — Operator workspaces for Bookings, Finance, and Operations turnover queues
  • Common Workflows — Procedures that align with Upcoming, Ongoing, Ended, and Canceled slices
  • Account Settings — Workspace-wide date defaults, emails, and notification categories
  • API Reference — Partner imports that create bookings with the same computed statuses
  • Glossary — Term definitions used across lifecycle docs
  • FAQ & Troubleshooting — Quick answers when filters disagree with Dashboard or Analytics
  • Get Help & Support — Escalation when lifecycle behaviour is blocked by permissions or account state
  • Using in-app support — Vivin product tickets when status rules are unclear

Navigation & bookmarks​

Pair with other Booking Lifecycle guide sections

Bookmark routes pair with Management Frontend Deep Links and Concepts hub — Navigation & bookmarks.

List views, Timeline, and portfolio context​

Turnover, cancellation, and collections workflows​

Tenant experience, integrations, and API contracts​

Deeper workflow reads​

Deeper concept reads​

  • Payment Allocation — Two-layer scheduled charges and Layer 2 receipt allocation tracked through lifecycle transitions
  • Tenant Portal — Contract signing and check-in triggers that interact with Upcoming and Ongoing statuses
  • Integrations & Distribution — Imported channel reservations follow the same computed status model
  • Services Marketplace — Portal add-on purchases during Ongoing stays
  • Tenant MCP — Booking-scoped automation that surfaces lifecycle-aware portal and payment context

Deeper API reads​

Operator habit hubs​

Day-to-day operator habits (lockout catch-up, pending receipts, payment triage, handoffs, and related playbooks) live on the Common Workflows habit hub.

Deep-link anchors for habit hubs

Lockout catch-up after password recovery​

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​

Key glossary terms​

Module documentation hubs​