Booking lifecycle and validations

A booking you send is queued first and created in the background; this page explains each stage, every check that can still refuse it, and how to confirm the result.

Before you start

Item	Value
Applies to	POST /<prefix>/bookings (Creating bookings) and the paid events of the Uniplaces and Housing Anywhere webhooks
You can read	Only the unit's calendar: GET /<prefix>/listings/{externalId}. The queue, the booking and its status are not available through the API
Who is told	The landlord, in VIVIN. Your platform is never called back

Lifecycle at a glance

1. You send the request. VIVIN checks your token and the shape of the body (and, on single-landlord prefixes, that the externalId belongs to that landlord), then answers 201 or an error. Availability and business rules are not checked yet, so partner routes never return 409 or 422.
2. VIVIN processes the queue: one queued booking about every 30 seconds, not necessarily in the order the requests arrived.
3. The booking is created or refused. Within about five minutes, the landlord gets an in-app notification either way (exceptions in How failures are reported and Retries and duplicates).

Queue statuses

Status	Meaning
new	Waiting for its turn
pending	Being processed
success	The booking was created
failed	Refused. The reason is kept and shown to the landlord
duplicate	Already imported: dropped without a booking or a notification (Retries and duplicates)

A failure caused by a temporary problem on VIVIN's side, such as a brief outage, goes back to new within 24 hours and is retried. Every other failure is final.

Checks during processing

VIVIN first drops the request as a duplicate if your platform already imported that reservation. Otherwise it runs these checks in order; the first one that fails refuses the booking, and its message is what the landlord sees.

Check	Passes when	Message when it fails
Unit lookup	externalId is linked to a unit for your platform, the unit is included in your feed, and neither the unit nor its property is archived	Listing not found for <platform> with externalId <id>
Blocked nights	The stay overlaps no blocked night of the unit: another booking with its preparation days, a manual block, or a block imported from another channel	Listing is unavailable from <first night> to <last night>
Platform payment	platformProviderPaymentValue is present and above 0. For Inlife and the Vivin Booking Engine, VIVIN works it out from the unit's rent when you leave it out	Platform provider payment value is required when booking comes from integration
Tenant overlap	Only when the matched tenant has a tenant category that does not allow Multiple concurrent bookings: the tenant has no other active booking on these dates	Tenant <first name> <last name> already has an active booking
Booking overlap	No booking on the unit that is not cancelled overlaps the dates	Date range overlaps with an existing booking on this listing

• Dates in messages are YYYY-MM-DD, and the blocked range is reported by its last blocked night.
• A stay can start on the day after a block's last night and end on a block's first night.
• VIVIN matches or creates the tenant before the date checks, so a refused booking can still leave a new tenant in the landlord's account.

Rules that only warn

The stay is already confirmed on your platform, so some rules are recorded instead of enforced. The booking is created, and VIVIN adds an entry to the Changelog on the booking's Contract Info tab that starts with Imported with warnings: and lists:

Rule	Warning
Capacity	Number of occupants (<n>) exceeds listing capacity (<capacity>)
Minimum stay	Stay of <n> nights is below the minimum of <min> nights
Maximum stay	Stay of <n> nights exceeds the maximum of <max> nights

Stay limits are compared in nights: the unit's short-term night limits when it has them, otherwise its month limits at 30 nights a month.

Rules that are not checked

availableFrom, bookingWindows, and that checkOutDate comes after checkInDate. Apply them on your platform before you send the booking (Listings and availability).

What the booking gets

Part	Detail
Tenant	An existing tenant with the same email or fiscal ID, otherwise a new one from the five tenant fields (Tenant fields)
Contract values	Rent with your platform's Markup and Extra Rent per Tenant, fees, deposit, due dates and times, from the unit, property and account (What VIVIN fills in)
Platform payment	platformProviderPaymentValue, recorded as a payment from your platform and set against the tenant's payment plan
Onboarding	The payment plan, then the contract and onboarding email, according to the landlord's settings
Calendar	The dates are blocked on the unit (Confirming the result)
Your reference	bookingId, stored as the booking's reference on your platform

In VIVIN, the landlord sees the booking as Upcoming, Ongoing or Ended by its dates, or Cancelled. See Booking lifecycle for how the app treats it afterwards.

Confirming the result

Read the unit again with GET /<prefix>/listings/{externalId}, which is always live. A created booking appears as a new unavailabilities entry:

• from is your check-in date.
• to is the last blocked night: the night before check-out, plus the landlord's Mid-term Prep days (Settings → Global Settings → Booking Defaults).
• reason is Unavailable.

The list (GET /<prefix>/listings) can take about 10 minutes to show it. Other channels pick up the block the same way: other partners through their feeds, iCal subscribers on their next poll. If no entry appears after a few minutes, the booking was refused or is still queued; the landlord has the reason.

How failures are reported

A refused booking is never reported to your platform. VIVIN tells the landlord:

Channel	Content
In-app notification	Failed to create booking from Platform <platform name>. Tenant email <email>., with the reason and the details you sent: tenant, email, phone, unit and dates
Email	The same text, to the landlord account's email address

A created booking gets New booking created from Platform <platform name>. Tenant email <email>., linked to the booking. Landlords can turn these in-app notifications off under Settings → Global Settings → In-app notifications → Scheduled bookings; the failure email does not depend on that switch.

If externalId matches no unit for your platform at all, VIVIN cannot tell which landlord the booking was for, so nobody is notified. Always take externalId from your latest feed.

Retries and duplicates

• Do not resend a request that got a 201. It is already queued.
• Duplicates are dropped silently. Every request is queued, but before creating a booking VIVIN checks whether your platform already imported the same bookingId into that landlord's account, including a booking that was later moved to other dates or another unit, cancelled or archived. If so, the request becomes duplicate: no second booking and no notification.
• Without a bookingId, or when the earlier booking was imported without one, a request with the same tenant email, unit and dates as an active booking from your platform is also a duplicate.
• Retry only after no response, a timeout or a 5xx. Wait a few minutes, since the first request may still be queued, then read the unit. If the stay is in unavailabilities, do not resend.
• A new request never changes an earlier booking. With the same bookingId it is dropped, even when the dates differ or the first booking was cancelled. Ask the landlord to change or recreate the booking, and use a new bookingId only for a new reservation.

Cancellations

No partner route cancels or changes a booking. Uniplaces and Housing Anywhere send cancellations through their webhooks. On every other platform, ask the landlord to cancel the booking in VIVIN. Once it is cancelled, its dates leave unavailabilities.

Troubleshooting

Symptom	Likely cause and fix
The landlord got no notification for a booking you sent	The externalId matched no unit at all, or the request was a duplicate. Check the ID against your feed
Listing is unavailable from … to …	Your platform sold nights that were blocked. Read to as the last blocked night (Reading availability)
Platform provider payment value is required…	Send platformProviderPaymentValue above 0, then send the booking again with the same bookingId
A corrected booking never arrives	It reused the bookingId of a booking already imported, so it was dropped. Ask the landlord to change the first booking
The booking exists but shows a warning	It breaks the unit's capacity or stay limits. The landlord decides whether to keep it

Related

• Creating bookings: the request body and request-time errors
• Listings and availability: unavailabilities, bookingWindows and freshness
• Webhooks and notifications: inbound webhooks for Uniplaces and Housing Anywhere
• Property and unit mapping: how externalId links to a unit
• Error handling: status codes and retries