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
} ] }
FieldMeaning
nameThe short display name of the listing (falls back to title). Use it in cards and breadcrumbs.
title, descriptionThe 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.
contentThe 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, accommodatesHeadline counts. bathrooms may be fractional (1.5). Any may be null.
bedsTotal sleeping places across the property (a bunk bed counts as two). null when unknown, never 0.
roomsThe 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).
destinationWhere 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.
basePriceThe 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.
areaSquareMetersFloor area in square metres, rounded. null when unknown, never 0. Convert on your side if you show square feet.
checkInTime, checkOutTimeLocal times as HH:MM, or null.
minNights, maxNightsThe listing's default stay limits, or null. Per-date minimums come from the availability endpoint and take precedence for a given stay.
positionThe manager's display order on this brand (0-based). Present on the list endpoint only.
Photo URLs are permanent, CDN-served and ordered — the first photo is the cover. Serve them directly; do not copy the files. 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)" }

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