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. Habit-specific shortcuts live under Related below.

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.

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.

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)

On Housing Anywhere listing pulls, nights outside that envelope already appear in unavailabilities so a calendar can honour the window without parsing bookingWindows — Housing Anywhere booking windows. POST /bookings still runs this window check against the stored ranges, not only the extra calendar rows.

Step 5: Stay Duration Validation​

On + Create New → Booking, Vivin checks stay length in whole months when the booking is created:

  • Minimum — enforced only when minStayPeriod is a positive number. 0 means no minimum.
  • Maximum — enforced only when maxStayPeriod is a positive number. 0 means no maximum. 12 is twelve months, not unlimited.

Marketplace POST /{platform}-integration/bookings honours listing JSON for those stay months, listing Capacity, and availableFrom instead — Creating Bookings — Honour listing. Occupied nights (unavailabilities) still reject on both paths.

Changing check-in or check-out on an existing booking does not re-run this check. Details: Listings & Availability — Maximum stay.

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. Marketplace POST /bookings does not send a tenant category — allowlisted channels assign Default for integration-created tenants when the person is new or still uncategorized — Creating Bookings — Tenant category.
  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.

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 durationOn Add Booking, stay is shorter than a positive minStayPeriod, or longer than a positive maxStayPeriod (0 skips that bound). Marketplace POST /bookings honours listing JSON instead — Honour listing
Capacity / available fromOn Add Booking, occupant count vs unit Capacity, and check-in vs listing available from. Marketplace POST /bookings honours listing JSON capacity and availableFrom. Occupied nights still reject.
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.

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.

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

ComponentHow it's calculated
Monthly rentFrom listing rentsPerMonth (variable) or rent (fixed). Partner POST /bookings does not send rent — Creating Bookings — Rent. Partial months are pro-rated. Do not multiply the GET headline rent by stay length when isRentFixed is false — Listings & Availability — Variable rent headline. Listing GET has no localRentCap — dual pricing (capped Rent plus Others) is frozen from the unit at create — Local rent cap.
Extra tenant surchargeextraPricePerTenant × numberOfExtraTenants × months. Listing GET publishes extraPricePerTenant as 0 when capacity is 1 — Extra price per tenant. Partner POST /bookings does not send Extra Charge euros — Creating Bookings — Extra Charge.
Second tenant identityEmpty until an operator fills Contract Info → Second tenant. Partner POST /bookings does not send a secondTenant object — occupant headcount is on that POST — Creating Bookings — Second tenant.
Guarantor identity / amountEmpty until an operator fills Contract Info → Guarantor. Partner POST /bookings does not send a guarantor object or guarantorAmount — occupant headcount does not fill that accordion — Creating Bookings — Guarantor.
Admin feeWhen the listing’s adminFeeMode is "fixed", one-time adminFeeValue. When "tiered", one-time amount resolved from adminFeeTiers by stay length (UTC days between check-in and check-out, check-out day not counted) — see Listings & Availability — Admin fee. Partner POST /bookings does not send the amount or tiers — Creating Bookings — Admin fee.
Cleaning feeProperty cleaningFeeValue, billed on the payment plan by Cleaning fee frequency (Every Month / one-time at confirmation / one-time at move-in). Partner POST /bookings does not send the amount or frequency — Creating Bookings — Cleaning fee. Frequency is not on listing JSON — Listings & Availability — Cleaning fee.
Exit feeProperty exit amount when Exit fee is on for the account and the property. One-time, due on check-out (does not block check-in). Not on listing JSON and not on partner POST /bookings — Listings & Availability — Exit fee.
DepositListing GET depositValue (computed property deposit — Computed deposit), plus Extra Deposit per Tenant × extra occupants at create. Partner POST /bookings does not send depositValue — Creating Bookings — Deposit. Extra Deposit euros are also not on that POST — Creating Bookings — Extra Charge. Held, not invoiced as income.
Bills includedProperty billsIncludedMaxValue ceiling copied onto the booking at create. Partner POST /bookings does not send billsIncludedMaxValue — Creating Bookings — Bills included. Used by Utilities overage math, not as a payment-plan line.
Contract type / day typeProperty Rental payment frequency (Daily / Fortnightly / Monthly) and Contract type (Traditional rental / Accommodation services / Others) copied onto the booking at create. Partner POST /bookings does not send contractType or contractDayType — Creating Bookings — Contract type. Listing GET also omits those keys.
Confirmation / check-in paymentsProperty Confirmation payments and Check-in payments copied onto the booking at create. Partner POST /bookings does not send bookingConfirmationRequirements or moveInRequirements — Creating Bookings — Confirmation payments. Listing GET also omits those keys.
Due date / Due MonthProperty Due date and Due Month, or account Tenant Due Day / Tenant Due Month when the property has no override. Partner POST /bookings does not send dueDay or dueDayMonth — Creating Bookings — Due date. Listing GET also omits those keys.
Check-in / check-out timesAccount Check-in time and Check-out time. Partner POST /bookings does not send checkInTime or checkOutTime — Creating Bookings — Check-in times. Listing GET also omits those keys.
Days before dueAccount Days before due date (when a scheduled charge appears as payable). Partner POST /bookings does not send daysBeforeDueAsPayable — Creating Bookings — Days before due. Listing GET also omits that key. There is no property-level override.
Check-in / check-out responsibleEmpty until an operator assigns a teammate. Partner POST /bookings does not send checkInResponsableId or checkOutResponsableId — Creating Bookings — Check-in responsible. Listing GET also omits those keys. There is no account-level or property-level default.
Lease purposeEmpty until an operator or tenant selects an allowed chip. Partner POST /bookings does not send leasePurpose — Creating Bookings — Lease purpose. Listing GET also omits that key. The Categories catalog is allowed values, not a default copied onto the stay. Make Lease Purpose mandatory does not reject channel create.
Deposit Refund LimitInherited from account Payments on every read until Contract Info overrides it (not snapshotted at create). Partner POST /bookings does not send depositReturnDueDay — Creating Bookings — Deposit Refund Limit. Listing GET also omits that key. There is no property-level override.
Booking tagsEmpty until an operator picks chips. Partner POST /bookings does not send bookingTags — Creating Bookings — Booking tags. Listing GET also omits that key. The Categories catalog is allowed values, not a default copied onto the stay.
Check-in / check-out maintenance ticketsCopied from the property Maintenances tab. Partner POST /bookings does not send createCheckInMaintenanceTicket or createCheckOutMaintenanceTicket — Creating Bookings — Maintenance tickets. Listing GET also omits those keys. Add booking can skip tickets for one reservation; Contract Info cannot flip the snapshot after import.
Ignore unit preparation daysOccupied nights including Mid-term Prep / Short-term Prep still reject. Partner POST /bookings does not send ignoreListingPreparationDays — Creating Bookings — Ignore unit preparation days. Listing GET also omits that key. Add booking can skip the prep buffer for one reservation; Contract Info cannot flip it after import.
Allow check-in date in the pastHonour listing JSON availableFrom. Partner POST /bookings does not send ignoreAvailableFrom — Creating Bookings — Allow check-in date in the past. Listing GET also omits that skip key (it does publish availableFrom). Add booking can skip the available-from month for one reservation; Contract Info cannot flip it after import.
Exclude from penalty feesOff until an operator ticks Exclude this booking from penalty fees on Contract Info. Partner POST /bookings does not send ignorePenaltyFees — Creating Bookings — Exclude from penalty fees. Listing GET also omits that key. Add booking has no create-time control.
Use check in date as contract start dateOff until an operator ticks Use check in date as contract start date / Use check out date as contract end date on Change contract start/end date. Partner POST /bookings does not send useCheckInDateInContract or useCheckOutDateInContract — Creating Bookings — Use check in date as contract start date. Listing GET also omits those keys. Add booking has no create-time control. Property Rental payment frequency still sets stored Start date / End date at create.
Send onboarding email & contractOn. Partner POST /bookings does not send sendOnBoarding — marketplace create always generates the contract (when a template exists) and queues the welcome email — Creating Bookings — Send onboarding. Listing GET also omits that key. Add booking can leave the box off. Account Onboarding No trigger still skips the welcome email.
Use unit contract rents and other contract detailsOn. Partner POST /bookings does not send useListingValues — marketplace create always copies unit and property contract values — Creating Bookings — Use unit contract rents. Listing GET also omits that key. Add booking can turn the box off.
Platform commissionRecorded from platformProviderPaymentValue for reconciliation. Does not change tenant rent except Vivin Booking Engine Daily stays shorter than one month — Creating Bookings — Platform commission.

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 the endpoints and fields above. Related integrator pages are linked inline where useful.

Pair with other Booking Lifecycle & Validations guide sections

Related below links enqueue validation rules to setup, companion API guides, operator workflows, and escalation paths.

Setup sequence after go-live​

Pair with other Booking Lifecycle & Validations guide sections

Complete Account Settings — Recommended setup order before partner traffic.

Documentation map & escalation​

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.

  • Creating Bookings — Request body, endpoint shape, and Swagger tips (honour listing JSON Capacity / stay / availableFrom — Honour listing; POST does not set rent — Rent; POST does not set Extra Charge / Extra Deposit euros — Extra Charge; POST does not set Second tenant identity — Second tenant; POST does not set Guarantor identity or amount — Guarantor; POST does not set cleaningFeeValue — Cleaning fee; POST does not set depositValue — Deposit; POST does not set adminFeeValue — Admin fee; POST does not set billsIncludedMaxValue — Bills included; POST does not set contractType / contractDayType — Contract type; POST does not set confirmation / check-in payments — Confirmation payments; POST does not set due day / due month — Due date; POST does not set check-in / check-out times — Check-in times; POST does not set days before due — Days before due)
  • Listings & Availability — Partial GET /listings availability checks before POST …/bookings accepts a payload (maxStayPeriod 0 is no maximum — Maximum stay)
  • 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​

Operator UI & settings​

Deeper concept reads​

Deeper workflow reads​

See Upstream & downstream workflows above for the same guides.

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​

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​

Key glossary terms​

Module documentation hubs​

Pair with other Booking Lifecycle & Validations guide sections

for screen-by-screen operator follow-up.

  • 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 — AI Assistant using Landlord MCP tools (hub)
  • Account Settings — Workspace-wide financial policies, templates, integrations, and operational defaults (hub)