Gateway API

The live, authoritative side: real-time availability and the booking operations. A gateway reservation is atomic — it checks the nights, takes them in Hostwise's calendar and closes them on every other sales channel the property is sold on, as one operation — and idempotent, so a network retry can never double-book. All routes carry your brand slug: /api/gateway/:brand/…, which must match your key's brand. Requires the gateway scope.

GET/api/gateway/:brand/availability

Query: listingId (or listingIds=a,b,c for bulk), from, to — inclusive, no range cap. price is the night's rate with your brand's markup applied (set on Hostwise's Markups page; 0 by default).

{ "listingId": "…", "currency": "EUR", "days": [
    { "date": "2027-01-10", "status": "available", "price": 320, "minNights": 3 }
] }
// bulk form returns { "listings": [ …one object per id… ] }
Fail closed. Any 5xx from this endpoint inside a checkout means "treat as unavailable". Never sell against a cached answer when the live one is unavailable — an error is not a yes.

POST/api/gateway/:brand/reservations

{
  "idempotencyKey": "your-unique-key-per-booking-attempt",   // required
  "listingId": "…",                                          // required
  "checkin":  "2027-01-10",                                  // required
  "checkout": "2027-01-17",                                  // required
  "guests": 4,
  "guest":  { "firstName": "…", "lastName": "…", "email": "…", "phone": "…" },
  "money":  { "accommodation": 2240, "currency": "EUR" },
  "reference": "YOUR-CONFIRMATION-CODE"                      // your own booking reference
}
// success
{ "alpyReservationId": 123, "status": "confirmed", "idempotentReplay": false }
ErrorMeaning
409 DATES_UNAVAILABLEAt least one night is not sellable. Show the guest a refreshed calendar; do not retry.
400Invalid input (dates, missing fields). Fix the request; do not retry as-is.
404Unknown or inactive listing, or not published to your brand.
5xx / timeoutOutcome unknown — retry with the SAME idempotencyKey. If the first attempt succeeded you get the same reservation back with idempotentReplay: true; if it failed you get a fresh attempt. Never generate a new key for a retry.
On success the nights are taken in Hostwise's calendar, closed on every other sales channel the property is sold on, and availability.changed + reservation.changed are emitted to every brand entitled to hear it — including your own site, which closes the dates on the account's other storefronts within seconds.

POST/api/gateway/:brand/reservations/:reference/cancel

:reference is the reference you supplied at creation. Marks the reservation cancelled, frees the nights everywhere the property is sold, and notifies the brands. Idempotent — cancelling twice returns { "status": "cancelled", "alreadyCancelled": true }. Cancellation is terminal.

POST/api/gateway/:brand/reservations/:reference/modify

Change the dates of an existing reservation. Body: { "checkin": "…", "checkout": "…" }. Applied atomically — the new nights are checked and taken and the freed ones released together, or nothing changes; refused with 409 DATES_UNAVAILABLE if the new range is not fully sellable.

POST/api/gateway/:brand/partner-quotes

A live price from a partner the account connected on Hostwise whose system is connected (an item marked pricing: "live" in /api/storefront/partners). Send what the guest wants; Hostwise asks the partner's system and returns its quote, valid until expires_at.

// request
{ "kind": "transfer", "start_date": "2027-01-10", "end_date": null, "adults": 2, "children": 1,
  "destination": "Val Thorens", "currency": "EUR", "details": { "airport": "GVA", "flight_number": "LX1234" } }
// response 200
{ "quote": { "quote_id": "q-8812", "total_cents": 15400, "partner_total_cents": 14000, "currency": "EUR", "expires_at": "2026-10-08T15:00:00Z", "partner": "Winteride" } }

Checkout pattern

  1. Guest reaches payment → call availability for the stay's range; if any night is not available, stop.
  2. Take payment on your side.
  3. Create the reservation with a stored idempotency key; on network failure, retry the same key.
  4. If creation returns DATES_UNAVAILABLE after a payment (rare race), refund per your policy — Hostwise has taken nothing.