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… ] }
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 }
| Error | Meaning |
|---|---|
409 DATES_UNAVAILABLE | At least one night is not sellable. Show the guest a refreshed calendar; do not retry. |
400 | Invalid input (dates, missing fields). Fix the request; do not retry as-is. |
404 | Unknown or inactive listing, or not published to your brand. |
5xx / timeout | Outcome 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. |
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" } }
total_centsis what you may sell at: the partner's answer plus the markup the account set on that partner in Hostwise (Partners → Scheduled services), if any;partner_total_centsis the partner's own answer and stays the booking's cost.404 no_connected_partner— the account has no connected partner of this kind (or removed the Partners add-on): sell from your own list, or not at all.409 unavailable— the partner cannot serve it (thedetailsays why);502 partner_error— the partner's system failed: show "not available right now", never a guessed price.- Book it by pushing the add-on through the Ingest API with the
quote_id: the partner's cost is the quote, and Hostwise books with the partner's system.
Checkout pattern
- Guest reaches payment → call availability for the stay's range; if any night is not
available, stop. - Take payment on your side.
- Create the reservation with a stored idempotency key; on network failure, retry the same key.
- If creation returns
DATES_UNAVAILABLEafter a payment (rare race), refund per your policy — Hostwise has taken nothing.