Skip to main content

Booking Lifecycle & Validations

First-time workspace setup

Understand post-import behaviour after Getting Started — Recommended Setup Sequence step 14 (Bookings) — partner POST /bookings returns 201 enqueue, then validations run asynchronously (Creating Bookings). Steps 11–12 (Tenant categories default for integrations, Emails lifecycle rules) shape portal and outreach on imported stays; finish Onboarding a New Property — Step 7 before you debug lifecycle mismatches in production. Guide pairing after go-live: Setup sequence after go-live (hub: API Reference — Setup sequence after go-live).

Finding your way in this guide

Start with Submission Flow and Processing Pipeline after 201 from Creating Bookings. Pair async outcomes with booking.* events in Webhooks & Notifications and business-rule failures in Error Handling. Calendar propagation and pricing rules: Calendar Propagation and Pricing Calculation. Non-linear operator habits (Lockout catch-up, Pending manual receipt approval, Reject/revert mistaken receipts, Portfolio segmentation by tenant category, Notification row-click navigation, Payment alert to receivables triage, Confirmation alert triage, Finance debt receivables triage, Handling a Late Payment collections, Finance Income status drill-down, Cash flow forecast drill-down) have matching Related subsections below. Full pairing matrix: Booking Lifecycle & Validations section cross-reference · API Reference — API guide cross-reference.

This page describes what happens inside Vivin after you submit a booking via the API, what validations are enforced, and how the booking progresses through its lifecycle.

Inspect schemas live

Use Integration Swagger on your API host to expand your platform’s bookings group, open POST …/bookings, and review queue status fields and validation error models. See Creating Bookings, API Reference index, and Authentication.

Integration Swagger — POST …/bookings with enqueue acknowledgement notes in the response schema

Read the 201 response description in Swagger: it documents the scheduled create-booking job acknowledgement, not the final Booking entity — matching the pipeline below.

Submission Flow​

Pair with other Booking Lifecycle & Validations sections

201 Created acknowledges enqueue only — request shape in Creating Bookings — Response. Prefer booking.* webhooks over polling — Webhooks & Notifications. Full endpoint map: Booking Lifecycle & Validations section cross-reference.

Your Platform                          Vivin
─────────────                          ─────
     │                                    │
     │  POST /bookings                    │
     │ ──────────────────────────────────► │
     │                                    │  1. Validate authentication
     │                                    │  2. Queue booking for processing
     │  201 Created (booking reference)   │
     │ ◄────────────────────────────────── │
     │                                    │  3. Look up listing by externalId
     │                                    │  4. Validate availability
     │                                    │  5. Validate booking windows
     │                                    │  6. Validate stay duration
     │                                    │  7. Create booking record
     │                                    │  8. Block dates on all channels
     │                                    │  9. Generate payment schedule
     │                                    │ 10. Trigger contract generation
     │                                    │ 11. Send notifications

Processing Pipeline​

Pair with other Booking Lifecycle & Validations sections

externalId lookup failures trace to Property & Unit Mapping. Availability fields come from Listings & Availability partial pulls. Full endpoint map: Booking Lifecycle & Validations section cross-reference.

Step 1: Queuing​

When your booking request is received, it is placed in an asynchronous processing queue (ScheduledCreateBooking). This ensures:

  • Your API call returns quickly (you don't wait for all validations)
  • Bookings are processed in order
  • Failed bookings can be retried

Each queued booking has a status:

StatusMeaning
NewQueued, waiting to be processed
SuccessBooking was created successfully
FailedBooking failed validation or processing

Step 2: Listing Resolution​

Vivin looks up the listing using:

  1. Your externalId + your platform identifier
  2. If no match is found, returns an error

For studio/single-unit properties, a fallback lookup by property ID is attempted if the full ID doesn't match.

Step 3: Availability Validation​

The system checks that the requested dates (checkInDate to checkOutDate) do not overlap with any existing:

  • Confirmed bookings on this listing
  • Manual unavailability blocks set by the property manager
  • Calendar blocks from other connected platforms (Airbnb, Booking.com, etc.)

If there is any overlap, the booking is rejected.

Step 4: Booking Window Validation​

If the listing has booking windows configured, Vivin checks that:

  • The checkInDate falls within the allowed start-date range (minStartDate to maxStartDate)
  • The checkOutDate falls within the allowed end-date range (minEndDate to maxEndDate)

Step 5: Stay Duration Validation​

Vivin checks that the booking duration respects:

  • Minimum stay period (minStayPeriod in months)
  • Maximum stay period (maxStayPeriod in months)

Step 6: Booking Creation​

If all validations pass, Vivin:

  1. Creates the booking record with status confirmed
  2. Creates or links the tenant - if a tenant with the same email already exists in the account, the existing record is linked; otherwise a new tenant is created
  3. Generates the payment schedule based on the listing's pricing configuration (fixed or variable monthly rents, admin fee, deposit, cleaning fee)
  4. Blocks the dates as an unavailability on the listing, which propagates to all other connected platforms on the next sync cycle
  5. Triggers contract generation if the property manager has configured auto-generation (via N8N webhook or similar)
  6. Sends notifications to the property manager (email, in-app)

Validation Summary​

Pair with other Booking Lifecycle & Validations sections

HTTP status mapping for failures: Error Handling (400, 404, 409, 422). Duplicate bookingId: Creating Bookings — Response. Full endpoint map: Booking Lifecycle & Validations section cross-reference.

ValidationWhen it fails
AuthenticationInvalid or missing Bearer token
Listing lookupexternalId does not match any mapped listing for your platform
AvailabilityRequested dates overlap with an existing booking or calendar block
Booking windowCheck-in or check-out dates fall outside the configured booking window
Stay durationStay is shorter than minStayPeriod or longer than maxStayPeriod
DuplicateA booking with the same bookingId already exists (no error - silently deduped)

Booking Statuses in Vivin​

After creation, a booking can move through the following statuses within Vivin:

StatusDescription
confirmedBooking is active and dates are blocked
checked_inTenant has moved in
checked_outTenant has moved out
cancelledBooking was cancelled - dates are released

Calendar Propagation​

Pair with other Booking Lifecycle & Validations sections

iCal subscribers poll on their own schedule — iCal feeds. Partial availability refresh: Listings & Availability. Full endpoint map: Booking Lifecycle & Validations section cross-reference.

When a booking is created from your platform:

  1. Immediate: The dates are marked as unavailable on the Vivin listing
  2. Next sync cycle (minutes): All other connected platforms (HousingAnywhere, Spotahome, Airbnb, etc.) receive updated availability through their respective sync mechanisms
  3. iCal subscribers: Calendar export is updated and available on next poll

This ensures that a booking on your platform automatically blocks the dates everywhere else, preventing double-bookings across the entire distribution network.

Pricing Calculation​

Pair with other Booking Lifecycle & Validations sections

Pricing fields originate from partial ListingDto rows — Listings & Availability — Field Reference. Operator reconciliation: Finance — Contract Values. Full endpoint map: Booking Lifecycle & Validations section cross-reference.

Vivin calculates the booking's financial terms based on the listing configuration at the time of booking creation:

ComponentHow it's calculated
Monthly rentFrom rentsPerMonth (variable) or rent (fixed). Partial months are pro-rated.
Extra tenant surchargeextraPricePerTenant × numberOfExtraTenants × months
Admin feeOne-time adminFeeValue
Cleaning feeOne-time cleaningFeeValue
DepositdepositValue (held, not invoiced as income)
Platform commissionRecorded from platformProviderPaymentValue for reconciliation

The generated payment schedule determines what the tenant owes and when, driving invoice generation and payment tracking within Vivin.

Management app vs integration API wording​

The management frontend (Bookings module, Dashboard, and related docs) exposes a computed timeline status (bookingStatus: upcoming, current, ended, canceled) derived from dates and cancellation — see Booking Lifecycle. That model is what operators filter and sort on in the UI.

This page’s integration tables (confirmed, checked_in, checked_out, queue states) describe the partner booking pipeline and stored integration fields after POST …/bookings runs. The two vocabularies answer different questions: “what did the API accept and record?” versus “where is this stay on the calendar today in the hub?”. When you map events to your own systems, rely on Integration Swagger response schemas on your API host for the exact fields your platform receives.

Booking Lifecycle & Validations section cross-reference​

Use this table when one validation topic naturally leads into another API guide, operator UI, or downstream workflow — each row links to the docs you should read before or after wiring POST …/bookings enqueue handling.

API topic / sectionPair with these docs
Submission FlowCreating Bookings — Response, Webhooks & Notifications (booking.* events)
Processing PipelineProperty & Unit Mapping, Listings & Availability
Validation SummaryError Handling, Creating Bookings (idempotent bookingId)
Calendar PropagationiCal feeds, Listings & Availability
Pricing CalculationFinance — Contract Values, Payment Allocation, Notifications — Payment overdue alerts → Handling a Late Payment — Step 1, Payment Allocation — Correcting mistaken receipts, Glossary — Invoiced floor (rent)

| Lockout catch-up after password recovery | Validated import backlog after sign-in recovery | Common Workflows — Lockout catch-up, Booking lifecycle, Webhooks & Notifications | | Pending manual receipt approval | Validated stays with pending move-in receipts | Common Workflows — Pending manual receipt approval, Managing a Check-in — Step 3b, Finance — Pending manual payments | | Reject/revert mistaken receipts | Duplicate validated imports | Common Workflows — Reject/revert mistaken receipts, Cancelling a Booking, Payment Allocation — Correcting mistaken receipts | | Portfolio segmentation by tenant category | Segment triage on validated bookings | Common Workflows — Portfolio segmentation, Settings > Tenant categories, Bookings — Other filters | | Notification row-click navigation | Validation failures vs alert row-click | API Reference — Notification row-click navigation, Common Workflows — Notification row-click navigation, Notifications module — Notification row-click navigation | | Payment alert to receivables triage | Computed Ongoing/Ended vs overdue alerts | API Reference — Payment alert to receivables triage, Common Workflows — Payment alert to receivables triage, Handling a Late Payment — Step 1 | | Confirmation alert triage | Upcoming validation vs confirmation alerts | API Reference — Confirmation alert triage, Common Workflows — Confirmation alert triage, Processing a New Booking — Step 5b | | Finance debt receivables triage | Lifecycle status vs Top debtors rank | API Reference — Finance debt receivables triage, Common Workflows — Finance debt receivables triage, Finance module — Finance debt receivables triage | | Handling a Late Payment collections | Integration surface vs operator collections Steps 1–6 | | Finance Income status drill-down | Status filters vs Income segments | API Reference — Finance Income status drill-down, Common Workflows — Finance Income status drill-down, FAQ — Finance Income status drill-down hub | | Cash flow forecast drill-down | Departure-week collections on forecast bars | API Reference — Cash flow forecast drill-down, Common Workflows — Cash flow forecast drill-down, FAQ — Cash flow forecast drill-down hub |

Pair with other Booking Lifecycle & Validations guide sections

Related below links enqueue validation rules to setup, companion API guides, operator workflows, and escalation paths. Pair Setup sequence after go-live with Getting Started — Recommended Setup Sequence; pair Companion API guides with API Reference hub. Topic-to-guide pairing in sections above: Booking Lifecycle & Validations section cross-reference. Full hub matrix: API guide cross-reference.

Setup sequence after go-live​

Pair with other Booking Lifecycle & Validations guide sections

Complete Account Settings — Recommended setup order before partner traffic. Hub parity: API Reference — Setup sequence after go-live. Full pairing matrix: Booking Lifecycle & Validations section cross-reference · API guide cross-reference.

Documentation map & escalation​

Pair with other Booking Lifecycle & Validations guide sections

Documentation-map bullets pair with Introduction — Section cross-reference and FAQ — Section cross-reference. Full pairing matrix: Booking Lifecycle & Validations section cross-reference.

Companion API guides​

Pair with other Booking Lifecycle & Validations guide sections

Companion guides share Bearer authorization or error shapes with this page — start from API Reference hub. Full pairing matrix: Booking Lifecycle & Validations section cross-reference.

  • Creating Bookings — Request body, endpoint shape, and Swagger tips
  • Listings & Availability — Partial GET /listings availability checks before POST …/bookings accepts a payload
  • Webhooks & Notifications — Push booking.* and unavailability.* events when Vivin configures a callback for your platform
  • Error Handling — HTTP status mapping for validation and conflict failures
  • Property & Unit Mapping — externalId lookup failures before availability checks run
  • iCal feeds — Calendar subscriber delays that can make availability validation look stale immediately after enqueue
  • Booking engine integration — White-label POST /bookings uses the same validation pipeline and queue states
  • Full listing feeds — Partner publish fields validated separately from booking enqueue rules
  • Authentication — Bearer token required on every POST …/bookings call
  • AI usage — Operator JWT ledger when reconciling import volume with internal LLM spend (integration Bearer keys return 401)

Upstream & downstream workflows​

Pair with other Booking Lifecycle & Validations guide sections

Workflow bullets pair with Common Workflows — Workflow cross-reference after partner traffic lands in the management app. Full pairing matrix: Booking Lifecycle & Validations section cross-reference.

Operator UI & settings​

Pair with other Booking Lifecycle & Validations guide sections

Operator UI rows validate the same inventory and permissions behind integration HTTP — pair with Account Settings — Tab cross-reference. Full pairing matrix: Booking Lifecycle & Validations section cross-reference.

Deeper concept reads​

Pair with other Booking Lifecycle & Validations guide sections

Concept reads pair with Concepts hub subsection index and Concept cross-reference. Full pairing matrix: Booking Lifecycle & Validations section cross-reference · API guide cross-reference.

Deeper workflow reads​

Pair with other Booking Lifecycle & Validations guide sections

Workflow reads pair with Common Workflows hub subsection index and Workflow cross-reference. Each workflow sub-guide also has its own Deeper API reads subsection with reciprocal companion API anchors — hub parity: API Reference — Deeper workflow reads. Full pairing matrix: Booking Lifecycle & Validations section cross-reference · API guide cross-reference.

Lockout catch-up after password recovery​

Pair with other Booking Lifecycle & Validations guide sections

Async validation jobs may complete during operator lockout — reconcile Upcoming / Ongoing filters after sign-in recovery. Hub parity: Common Workflows — Lockout catch-up after password recovery. Full pairing matrix: booking-lifecycle--validations-section-cross-reference · API guide cross-reference.

Pending manual receipt approval​

Pair with other Booking Lifecycle & Validations guide sections

Successful validation creates payment schedules; move-in receipts may still await Approve payments — pair with Payment Allocation. Hub parity: Common Workflows — Pending manual receipt approval. Full pairing matrix: booking-lifecycle--validations-section-cross-reference · API guide cross-reference.

Reject/revert mistaken receipts​

Pair with other Booking Lifecycle & Validations guide sections

Failed validation vs duplicate successful imports pair with Cancelling a Booking and receipt Reject / Revert. Hub parity: Common Workflows — Reject/revert mistaken receipts. Full pairing matrix: booking-lifecycle--validations-section-cross-reference · API guide cross-reference.

Portfolio segmentation by tenant category​

Pair with other Booking Lifecycle & Validations guide sections

Validation assigns integration-default tenant category — pair with Settings > Tenant categories before high import volume. Hub parity: Common Workflows — Portfolio segmentation by tenant category. Full pairing matrix: booking-lifecycle--validations-section-cross-reference · API guide cross-reference.

Notification row-click navigation​

Pair with other Booking Lifecycle & Validations guide sections

Async validation 400s are distinct from /notifications row-click — operators triage import alerts only after enqueue succeeds. Hub parity: API Reference — Notification row-click navigation. Full pairing matrix: Booking Lifecycle & Validations section cross-reference · API guide cross-reference.

Payment alert to receivables triage​

Pair with other Booking Lifecycle & Validations guide sections

Computed Ongoing/Ended statuses drive payment overdue row-click targets — confirm Payment Plan on the opened booking before Debt Aging. Hub parity: API Reference — Payment alert to receivables triage. Full pairing matrix: Booking Lifecycle & Validations section cross-reference · API guide cross-reference.

Confirmation alert triage​

Pair with other Booking Lifecycle & Validations guide sections

Upcoming computed status pairs with Booking created alert triage — validation success does not approve confirmation receipts. Hub parity: API Reference — Confirmation alert triage. Full pairing matrix: Booking Lifecycle & Validations section cross-reference · API guide cross-reference.

Finance debt receivables triage​

Pair with other Booking Lifecycle & Validations guide sections

Ongoing/Ended stays drive Top debtors after Payment alert to receivables triage — review lifecycle on the opened booking first. Hub parity: API Reference — Finance debt receivables triage. Full pairing matrix: Booking Lifecycle & Validations section cross-reference · API guide cross-reference.

Handling a Late Payment collections​

Pair with other API Reference hub sections

Partner integration reads on Booking Lifecycle Validations do not replace operator collections — payment overdue in-app rows still need Handling a Late Payment — Steps 1–6 after receivables triage. Hub parity: Common Workflows — Handling a Late Payment collections hub. Full pairing matrix: booking-lifecycle-validations-section-cross-reference · API guide cross-reference.

Finance Income status drill-down​

Pair with other Booking Lifecycle & Validations guide sections

Computed Ongoing/Ended statuses shape which bookings appear in Income → In debt month-scoped modals — booking-level rank stays on Debt Aging. Hub parity: API Reference — Finance Income status drill-down. Full pairing matrix: Booking Lifecycle & Validations section cross-reference · API guide cross-reference.

Cash flow forecast drill-down​

Pair with other Booking Lifecycle & Validations guide sections

Departure-week approved collections on Cash flow forecast bars reflect lifecycle timing — distinct from Income status segments. Hub parity: API Reference — Cash flow forecast drill-down. Full pairing matrix: Booking Lifecycle & Validations section cross-reference · API guide cross-reference.

Key glossary terms​

Pair with other Booking Lifecycle & Validations guide sections

Glossary rows pair with Glossary cluster cross-reference and receipt-dispute workflows. Full pairing matrix: Booking Lifecycle & Validations section cross-reference.

Module documentation hubs​

Pair with other Booking Lifecycle & Validations guide sections

Module hubs pair with Modules — Module cross-reference for screen-by-screen operator follow-up. Full pairing matrix: Booking Lifecycle & Validations section cross-reference.

  • Audit module — Manual blocks that can cause availability validation failures across channels (hub)
  • Tenants module — Operator enrichment when validation creates thin tenant profiles on high-volume imports (hub)
  • Finance module — Portfolio ledgers and Deposits tab refund queue once validated imports reach Ended status (hub)
  • Utilities module — Operator overage billing after validated stays exceed billsIncludedMaxValue ceilings from partial pulls (hub)
  • Operations module — Maintenance tickets, cash flows, and check-in/out coordination (hub)
  • Dashboard module — Post-login KPI snapshot with bell notification triage (hub)
  • Analytics module — Month-range portfolio KPI charts with rankings and heatmaps (hub)
  • Listings module — Property wizard, Channels tab, and unit management (hub)
  • Properties workspace — Legacy /properties URL redirects into Listings (hub)
  • Booking engine details — Rich marketplace payload editor via the Full integration pill (hub)
  • Sales module — Portfolio availability and channel manager connections (hub)
  • Inbox module — Portfolio-wide WhatsApp workspace (hub)
  • Notifications module — Full /notifications history with search and filters (hub); Payment overdue alerts when validated imports leave unpaid schedules
  • AI Chat module — Vivin-internal AI Assistant using Landlord MCP tools (hub)
  • Account Settings — Workspace-wide financial policies, templates, integrations, and operational defaults (hub)