Loading...
This reference describes Haven's native Hospitable Public API integration: what Haven currently reads from Hospitable, what Haven writes back, how polling and webhooks work, and which fields or operations are not supported.
For connection and setup instructions, see Hospitable Integration.
Haven reads supported:
When the connection has the required write scopes and the mapped listing is writable, Haven can write:
%guidebook% enrichable shortcode when that feature and property setting are enabledThis article covers the native Hospitable PMS connection stored in Haven as HOSPITABLE. It does not describe the separate Airbnb connection product.
Haven fetches the property with Hospitable's details and bookings expansions, normalizes the response, and writes only fields with a defined supported value.
Haven persists:
public_name, when presentnamesummary, when presentdescriptioncapacity.maxcapacity.bedroomscapacity.bathrooms
property_typeroom_type is one of:
entire_home, entire home, or entire_place → Entire placeprivate_room or private room → Private roomshared_room or shared room → Shared roomhotel_room or hotel room → Hotel roomhouse_rules.pets_allowedhouse_rules.events_allowedhouse_rules.smoking_allowedHaven does not guess a listing type when Hospitable sends an unrecognized room type.
Haven persists supported values for:
-0500Hospitable does not control Haven's host-owned display-location override.
Haven maps:
details.space_overview → About the spacedetails.guest_access → Guest accessdetails.other_details → Other notesdetails.additional_rules → Additional house rulesdetails.house_manual → During your staydetails.neighborhood_description → Neighborhood descriptiondetails.getting_around → Getting arounddetails.wifi_name → Wi-Fi networkdetails.wifi_password → Wi-Fi passwordother_details is intentionally not written to Haven's check-in instructions. It is a general Hospitable catch-all and remains under Other notes.
Haven maps recognized Hospitable amenity names to Haven amenity fields. Unknown amenity names are retained in sync diagnostics but are not forced into an unrelated amenity.
If Hospitable supplies an amenity array, the Amenities section is considered supplied for sync-lock purposes even when some entries do not have a Haven equivalent.
The current normalizer can receive or retain these values without writing them to a host-editable Haven field:
capacity.bedspicturecreated_at and updated_at timestampssite_urlsThe listed value is used for listing-status behavior rather than public Haven visibility. A channel-unlisted property can remain visible and bookable on Haven.
calendar_restricted is stored as integration restriction metadata. It controls whether Haven can write that property's calendar; it is not a Haven property-content field.
Haven fetches photos from Hospitable's dedicated property-images endpoint. That endpoint exposes the property's Direct-channel gallery only.
This means:
For each returned photo, Haven uses:
Photo behavior:
Haven recognizes these exact Hospitable fee names:
cleaning_fee → cleaning feelinens_fee → linen feecommunity_fee → community feeresort_fee → resort feemanagement_fee → management feeHospitable money objects are converted from cents to the property's major currency unit. Percent fee rows are normalized as numeric values; the current field selector does not distinguish fixed and percent rows for the exact names above. Hosts should verify any percentage-based fee after import rather than assuming Haven recreated its charging semantics.
Haven maps:
occupancy_based_rules.guests_included → the extra-guest thresholdoccupancy_based_rules.extra_guest_fee → additional price per personoccupancy_based_rules.pet_fee → pet feebase → Haven security depositIf Hospitable omits the pet-fee frequency or sends an unknown value, the current normalizer records it as Per stay.
Haven maps percent discounts with these exact names:
weekly → weekly discountmonthly → monthly discountOther discount names are not mapped. Haven does not recreate arbitrary promotion rules, listing markups, coupons, or channel-specific conditions from this property payload.
On initial property creation:
After import, inbound property sync does not silently replace the property's currency. The imported currency remains marked as a supplied integration field for locking, but the host's established property currency is not rewritten on later syncs.
Hospitable supplies cancellation policy as an array of text labels or descriptions. Haven's current deterministic text matcher maps:
super strict or 50% refund → Super strictfirm, or both 30 days and full refund → Strictmoderate, five days, or 5 days → Moderateflexible or 24 hours → FlexibleIf Hospitable sends non-empty cancellation text that does not match those patterns, the current importer records Flexible. This path writes Haven's legacy cancellation-policy preset and marks cancellation policy as configured; it does not recreate arbitrary Hospitable prose as custom stacked refund tiers.
Any non-empty Hospitable cancellation-policy response marks the cancellation field as supplied and locks it unless the host explicitly overrides that field in Haven.
For each returned calendar day, Haven can consume:
price.amountmin_stayclosed_for_checkinclosed_for_checkoutstatus.availableHospitable calendar prices are cents. Haven divides the amount by 100 and writes a one-day PriceOverride for each positive returned price.
Important details:
Haven converts per-day min_stay values into date-range minimum-stay overrides. Consecutive days with the same minimum are grouped together. Each refresh replaces overlapping integration-sourced ranges so stale minimums do not accumulate.
When Hospitable explicitly reports the listing as unlisted, Haven treats channel minimum-stay and check-in/check-out rules as potentially synthetic placeholders:
Haven stores closed_for_checkin: true and closed_for_checkout: true as per-date check-in/check-out blocks. The returned window is replaced on each sync.
These are per-day restrictions, not a single guessed weekly rule.
For ordinary status.available: false days, Haven creates partner-origin UNAVAILABLE events labeled Blocked via Hospitable.
Haven avoids duplicate blocks by excluding dates already covered by:
Each calendar refresh reconciles the integration-created block set in the returned range.
AVAILABILITY_WINDOWHospitable can return future days as:
available: falsereason: BLOCKEDsource_type: AVAILABILITY_WINDOWHaven treats this as the boundary of Hospitable's rolling booking window, not as a real owner block or reservation.
Haven therefore:
UNAVAILABLE events for those daysThis prevents a 12-month Hospitable window from appearing as a permanent block across every later date in Haven.
Hospitable reservations become partner-origin UNAVAILABLE events in Haven. They are not recreated as paid Haven bookings.
Haven uses:
The calendar note includes the source platform, the guest's first name and last initial when available, and the guest count.
Haven does not turn Hospitable reservation financial data into:
For the connector's normalized reservation import:
The regular reservation poll sends every returned row through the reservation handler, which uses current status to create, update, or remove the mirrored unavailable event.
For a non-cancelled reservation with a usable email and dates, Haven upserts Guest CRM data with:
Initial import also queues a connection-scoped guest-history backfill. The connector's historical guest import scans confirmed-category reservations from approximately five years ago through one year ahead and associates only reservations whose external property is mapped to Haven.
Guest details are reservation-scoped. Haven does not have a standalone native Hospitable guest webhook handler.
Review import requires the reviews:read scope.
For a review with public text, Haven upserts a testimonial using:
Newly imported testimonials start hidden from the public property page until Haven's featured-review evaluation or the host's curation makes them visible. A later sync updates provider-owned review fields without overwriting host-controlled visibility choices.
During bulk review sync, private feedback can be stored separately for host-only Guest Insights with:
Private feedback is not published as testimonial copy.
Bulk review sync:
For native Hospitable PMS webhooks, only review.created and review.changed are handled. Other review lifecycle names are not treated as native PMS testimonial updates.
Native Hospitable message webhooks are reservation-scoped.
When the Guest messaging inbox feature is enabled for the host:
message.created can create a Haven conversation and message for a mapped reservation.message.updated updates reactions for a message Haven already ingested.Messages without a reservation_id are acknowledged but not attached to a Haven conversation. A reservation must have an active EXT_RESERVATION mapping to a Haven event.
Haven suppresses:
sent_reference_idWhen the inbox feature is off for the host, inbound message webhooks do not create Haven conversations.
Haven pushes a confirmed direct booking only when:
CONNECTEDHaven's create-reservation request sends:
property_idcheck_incheck_outguests
adultschildreninfantspetsguest
financials, in cents
other_fees row when positiveother_fees row when positivelanguage: enreservation_code using the Haven event IDHaven subtracts stay-level, discount-code, and direct-booking discounts from accommodation because Hospitable's payload has no negative discount line. Night-level promotions already included in Haven's accommodation calculation are not subtracted again.
When a direct-booking discount exists, Haven adds a note such as [Haven direct booking discount: -$25.00]. Haven checks the sent line-item total against the Haven total and reports a mapping discrepancy greater than one cent.
The payload does not send:
Haven remains the financial system of record for the direct booking.
Before retrying an ambiguous create attempt, Haven searches Hospitable for an exact non-cancelled match on:
After a successful create, Haven maps the Hospitable reservation ID to the Haven event. Reservation webhooks then recognize and suppress the ordinary create echo. A short race guard also suppresses same-property, same-date echoes while a recent outbound push is still being committed.
The native Hospitable calendar domain is two-way when the connection has calendar:write and the property is not calendar-restricted.
Haven's outbound calendar body can contain, per date:
availableclosed_for_checkinclosed_for_checkoutLarge date ranges are split into 365-day chunks.
In two-way mode, Haven does not send the fully materialized calendar back wholesale. A per-day field is included only when Haven can identify it as Haven-authored.
Current rules:
available: false.closed_for_checkin: true.closed_for_checkout: true.Haven does not currently send available: true through this provenance-filtered path, because that could reopen a date owned by Hospitable. It also does not send false to clear a partner's check-in/check-out restriction.
With Manage pricing in Haven on:
Haven can cancel a mapped Hospitable reservation by calling the reservation cancel endpoint with initiated_by: host.
Haven does not have a general update-existing-reservation write path for dates, guest details, notes, or charges.
If the dates are unchanged and the booking is not cancelled, the reservation webhook is treated as an echo. Haven does not import guest-count, guest-contact, note, or financial edits into the paid Haven booking.
Haven currently pushes cancellation, but it does not push a general date, guest, note, or charge update to an existing Hospitable reservation.
Before Haven creates a temporary hold for requested dates on a mapped native Hospitable property, Haven fetches that exact date range from Hospitable's live calendar.
The guard:
status.available: false as blockedIf Hospitable cannot be reached, Haven records the integration error and fails open so a provider outage does not make every Haven property unbookable. Haven's own calendar, booking transaction, and overlap checks still apply.
After payment confirmation, Haven performs another non-blocking external check for warning and mitigation purposes; at that stage it does not reverse the already-confirmed payment solely because the warning check found a conflict.
Reservation-thread sends use Hospitable's POST /v2/reservations/{reservation}/messages endpoint and require:
message:writeHaven sends the message body and stores Hospitable's sent_reference_id for echo matching.
Inbound threading into Haven requires the Guest messaging inbox feature. Outbound delivery to Hospitable additionally requires the separate Send guest messages to Hospitable feature. If either feature is unavailable, only the enabled part of the bidirectional path runs.
Guest-originated Message Host email remains the durable delivery path. When Hospitable routing is enabled and succeeds, the message is also threaded into Hospitable; if it is unavailable or rejected, the existing host email still sends.
Hospitable documents rate limits of two messages per minute per reservation thread and 50 messages per five minutes per access token. Haven does not currently send message images through this flow, and pre-booking inquiry messaging is not wired.
When the Hospitable guidebook shortcode feature is enabled and the property's sharing toggle is on, Haven writes the property's public guide URL into Hospitable's guidebook enrichable shortcode.
Behavior:
HOSPITABLE Public API connection.null to clear the shortcode.The feature is separately gated from guest messaging.
For each property the host selected, Haven:
details and bookings.AVAILABILITY_WINDOW.Initial calendar discovery requests approximately 760 days so Haven can observe booking windows up to roughly 24 months and price the actual bookable horizon.
Haven imports only properties the host selected. A property.created webhook auto-imports a new property only when the host has explicitly turned on automatic import.
The Sync action queues:
A calendar-only or reservations-only manual request uses the same combined calendar-and-reservations job. Manual property/calendar sync does not itself queue the separate review poll.
In production:
The normal calendar poll requests:
AVAILABILITY_WINDOW boundary can be detectedReservation polling reads approximately 30 days back and 730 days ahead, includes guest and property data, updates existing mirrors, and removes orphaned partner-reservation events that disappear from the complete returned window.
In production:
This poll refreshes property content and Direct photos. It does not refresh the calendar; calendar and reservations use their separate poll.
In production:
This is the deterministic safety net behind review webhooks.
Haven currently has exact native handlers for:
property.createdproperty.changedproperty.deletedproperty.mergedreservation.createdreservation.changedreview.createdreview.changedmessage.createdmessage.updatedintegration.disconnectedThere is no native Hospitable calendar webhook in this implementation. Calendar changes arrive through polling.
Unknown property, reservation, review, message, or integration action names are logged through an unhandled/fallback path and do not silently mutate host-facing data.
property.createdproperty.changeddetails and bookings.Calendar and reservations converge through their hourly safety poll.
property.deletedproperty.mergedFor each Hospitable previous_id merged into new_id, Haven:
Haven does not automatically attach the old Haven property to new_id. The host can re-link it to the surviving listing.
reservation.createdreservation.changedreview.created and review.changedThe webhook path does not perform the full private-feedback bulk import; the review poll provides that convergence path.
message.createdmessage.updatedintegration.disconnectedDISCONNECTED.Haven verifies the signature header against a lowercase hexadecimal HMAC-SHA256 digest of the exact raw request body using Haven's Hospitable webhook secret.
The comparison is timing-safe. Missing, malformed, or incorrect signatures return 401.
After verification and normalization:
CONNECTED are dropped; integration.disconnected is allowed through so cleanup can finish.Hospitable's webhook envelope id is Haven's idempotency key.
Haven atomically deduplicates on provider plus idempotency key in the database. The short deduplication retention window is 60 seconds, which suppresses immediate retries and concurrent delivery races.
Reservation, message, and outbound mapping logic adds domain-specific idempotency beyond this short delivery window.
401200 so the same malformed body is not retried indefinitely200200200500 so Hospitable can retryThe HTTP route verifies, normalizes, deduplicates, and enqueues. Property, reservation, review, and message mutations run later in the worker, so a later handler failure is recorded on the sync job rather than changing the original webhook acknowledgement.
Haven stores a redacted webhook audit sample and validates external REST and webhook payloads for schema drift. Guest contact needed by reservation handling stays only in the minimized worker payload; heavy unused notes and charge details are removed before queue persistence.
Only supported fields Hospitable actually supplied are marked Synced from Hospitable.
Common supplied fields include:
AVAILABILITY_WINDOWAn absent or unmappable property field normally remains editable.
For supported property-content and fee fields, the host can select the sync badge and choose Edit in Haven.
While overridden:
Choosing Re-sync from Hospitable returns the field to inbound management.
Calendar behavior differs from property-content overrides:
AVAILABILITY_WINDOW booking-window field remains partner-managed.Haven does not currently:
available: true to reopen a partner-owned date through the current provenance-filtered calendar pathfalsereview.created and review.changed as review updatesNew to Haven?
Haven is the direct booking platform these guides are written for — a branded site, secure payments, and guest relationships you own. Build yours free.
Free to build · No credit card · Private until you publish
© 2026 Book With Haven, LLC.