Storefront API
The read side of your brand: the published catalogue, per-day availability and pricing, and stay quotes. This is what your website's pages and caches are built from. It returns only listings published to your brand — the same listing can be on sale on one of an account's brands and absent from another.
GET/api/storefront/listings
The brand's published listings, in display order, with content and photos.
{ "brand": "yourbrand", "listings": [ {
"id": "…", "name": "…", "title": "…",
"description": "…", "propertyType": "apartment",
"address": "…", "city": "…", "destination": "Val Thorens", "lat": 45.29, "lng": 6.58,
"bedrooms": 2, "bathrooms": 1, "accommodates": 6,
"beds": 4, "areaSquareMeters": 62,
"rooms": [
{ "kind": "bedroom", "kindLabel": "Bedroom", "title": "Bedroom 1",
"beds": [ { "type": "single", "qty": 2, "label": "Single bed" } ],
"bedsText": "2 single beds" },
{ "kind": "living_room", "kindLabel": "Living room", "title": "Living room",
"beds": [ { "type": "sofa", "qty": 1, "label": "Sofa bed" } ],
"bedsText": "1 sofa bed" },
{ "kind": "full_bathroom", "kindLabel": "Full bathroom", "title": "Full bathroom",
"beds": [], "bedsText": null }
],
"currency": "EUR", "basePrice": 210,
"photos": ["https://…", "…"], "thumbnail": "https://…",
"content": { "summary": "…", "space": "…", "access": "…",
"interactionWithGuests": null, "neighborhood": "…",
"transit": "…", "notes": null },
"checkInTime": "16:00", "checkOutTime": "10:00",
"minNights": 2, "maxNights": null,
"amenities": { "unit": ["Airconditioning", "Dishwasher", "…"],
"building": ["Lift", "Ski locker room"] },
"customFields": { "Luna park in the garden": "Open 10:00–18:00",
"Ski locker number": "B12" },
"position": 0
} ] }
| Field | Meaning |
|---|---|
name | The short display name of the listing (falls back to title). Use it in cards and breadcrumbs. |
title, description | The long marketing title and the full description as one text. description is the parts of content joined in order. Both, and content, may be brand-specific: a listing can carry a custom description assigned to your website, and you receive that one; otherwise the primary. |
content | The description as separate parts — summary, space, access, interactionWithGuests, neighborhood, transit, notes — so your page can lay out its own sections. Every key is always present; a part that was not written is null. |
bedrooms, bathrooms, accommodates | Headline counts. bathrooms may be fractional (1.5). Any may be null. |
beds | Total sleeping places across the property (a bunk bed counts as two). null when unknown, never 0. |
rooms | The room arrangement, in the manager's order: one entry per room with its kind (a stable key such as bedroom, living_room, full_bathroom, half_bathroom, kitchen, balcony, office …), a display kindLabel, the room's title, and its beds — each with a stable type (single, bunk, double, queen, king, sofa), a qty and a display label. bedsText is a ready-to-print line ("2 single beds · 1 sofa bed") or null for a room with no beds. Always an array, empty when the listing has not been arranged. Render it as sleeping arrangements; iterate it, and treat unknown kind or type values as display-only (new ones can appear). |
destination | Where the listing sells — the manager's destination name as plain text (a resort, a town), or null. Use it to place a listing you have not seen before in your own destination grid without a human typing it. |
basePrice | The listing's base nightly rate in currency, major units (210, not cents), or null, with the brand's markup applied (Markups in Hostwise, or the listing's own override for the brand on its Pricing tab; 0 by default - every price this API returns carries it). It is the "from" price for a card before dates are chosen; a quote uses the per-date rates from the availability endpoint. |
areaSquareMeters | Floor area in square metres, rounded. null when unknown, never 0. Convert on your side if you show square feet. |
checkInTime, checkOutTime | Local times as HH:MM, or null. |
minNights, maxNights | The listing's default stay limits, or null. Per-date minimums come from the availability endpoint and take precedence for a given stay. |
position | The manager's display order on this brand (0-based). Present on the list endpoint only. |
amenities carries display-ready titles from Hostwise's amenity catalogue, grouped as unit (the apartment) and building (shared
facilities), alphabetical; both arrays are always present and may be empty — render them as-is, no
mapping needed.customFields carries whatever the property manager defined for their own
account — things the manager wanted to tell guests beyond the standard fields. Keys are the
operator's own labels; values are strings, numbers or booleans; the object is always present and may be
empty. Two consequences for your site: the keys are not a fixed schema — iterate the
object rather than reading a named key, because a manager can add or rename a field at any time — and
every custom field with a value is sent, so an absent key simply means it was not filled in for that
listing. HTML-escape the labels as well as the values: both are operator-entered text.GET/api/storefront/listings/:id
One listing, same shape. 404 unless it is published to your brand.
GET/api/storefront/listings/:id/availability
Per-day availability and price over an inclusive range; price carries the brand's markup. Query: from, to
(both YYYY-MM-DD, required; range at most 400 days).
{ "id": "…", "availability": [
{ "date": "2027-01-10", "status": "available", "price": 320, "minNights": 3 },
{ "date": "2027-01-11", "status": "booked", "price": 320, "minNights": 3 }
] }
status is one of available | booked | blocked. For selling
purposes the last two are identical: not sellable.
POST/api/storefront/quote
Which published listings can host a stay, and at what total price (the brand's markup included).
// request
{ "from": "2027-01-10", "to": "2027-01-17", "guests": 4 }
// response
{ "from": "…", "to": "…", "nights": 7, "guests": 4, "results": [
{ "id": "…", "title": "…", "total": 2240, "currency": "EUR", "perNight": 320 }
] }
GET/api/storefront/partners
What this account can sell alongside a stay: the services of the partners the account connected on Hostwise (transfers, rentals, passes…), each with its menu and prices. Hostwise publishes it; your site shows and sells it. There is nothing to keep up to date by hand: whatever the account connects, and whatever a partner changes in its menu, is in the next read.
// response
{ "brand": "yourbrand",
"partners": [
{ "kind": "transfer", "label": "Transfers", "partner": "Winteride", "connected_system": true, "markup_pct": 10,
"items": [
{ "id": 52, "name": "Airport transfer GVA → resort", "description": "Up to 8 passengers",
"unit": "per_booking", "unit_label": "per booking", "pricing": "fixed", "price_cents": 14300, "partner_price_cents": 13000, "currency": "EUR", "price_label": "143.00 EUR" },
{ "id": 53, "name": "Private van, any route", "unit": "per_booking", "pricing": "live", "price_cents": null, "currency": "EUR", "price_label": "live price" }
],
"quotes": { "endpoint": "/api/gateway/yourbrand/partner-quotes", "method": "POST", "body": { "kind": "transfer" } } },
{ "kind": "rental", "label": "Rentals", "partner": "Ski Shop", "connected_system": false, "items": [ … ], "quotes": null }
],
"how_to_book": "push the booking through /api/ingest with items:[{id, qty}] from this menu (a live item: book with the quote_id from the quotes endpoint)" }
- Fixed items carry their price: show it, add your own margin if you wish, sell. When the account set a markup on that partner in Hostwise (Partners → Scheduled services),
price_cents/price_labelalready carry it, the partner's own price ispartner_price_centsand the partner entry saysmarkup_pct; otherwise the price is the partner's own andmarkup_pctisnull. - Live items (
pricing: "live") have no price here: ask the partner's price at checkout through the Gateway API (POST /api/gateway/:brand/partner-quotes), then book with thequote_id. - Booking: push the add-on through the Ingest API with
items: [{ "id", "qty" }](andquote_idfor a live item). Hostwise prices the partner's side from its menu, opens the request to the partner, and the partner confirms in its portal or straight from its own system. - Read it with the catalogue; refresh hourly and on a page that sells extras.
Displaying photos
Photo URLs are CDN links that accept sizing parameters in the URL. Ask for the size you need — copy this helper (framework-free, browser or Node) rather than serving the full-resolution originals:
export function imageVariant(url, { w, h, q = 'auto', f = 'auto' } = {}) {
if (typeof url !== 'string'
|| !url.includes('/image/upload/')) return url;
const t = [w && `w_${w}`, h && `h_${h}`, q && `q_${q}`, f && `f_${f}`].filter(Boolean).join(',');
return t ? url.replace('/image/upload/', `/image/upload/${t}/`) : url;
}
// Best-resolution rendering: offer several widths and let the BROWSER choose by slot size and
// screen density (a 480px slot on a 3x phone wants 1440 real pixels). Use with <img>:
// <img src="${imageVariant(photo, { w: 960 })}"
// srcset="${imageSrcset(photo)}"
// sizes="(max-width: 600px) 100vw, 33vw" loading="lazy" alt="">
export function imageSrcset(url, widths = [480, 960, 1440, 2560]) {
return widths.map((w) => `${imageVariant(url, { w })} ${w}w`).join(', ');
}
imageVariant(photo, { w: 480 }) // fixed-size thumb (small slots)
imageSrcset(photo) // responsive — sharp on every screen
q_auto picks compression per image; f_auto serves WebP/AVIF to browsers
that accept them. Prefer imageSrcset + sizes for listing cards and heroes — it is what makes
photos sharp on phones and Retina screens without shipping desktop bytes to mobile. URLs without the sizing segment pass
through untouched, so both helpers are always safe to call. Always HTML-escape URLs before inserting
them into markup.
Caching guidance
- Keep a copy of the catalogue and availability in your own store and serve pages from it — fast for guests, and resilient if Hostwise is briefly unreachable.
- Refresh on a schedule (hourly is typical) and on webhook receipt for the named listings and dates.
- Treat your cache as a browsing surface only. The moment money moves, confirm through the Gateway API, which is always live.