Reference

Objects and Enums

The canonical vocabulary. These shapes are the same whichever distributor the data came from.

Every supplier's own structure is translated into the shapes below before it reaches you — which is the point of the aggregator. Field names here are the names you will see in every response.

Money

An amount in a currency. Amounts are JSON numbers in the currency's major unit: 164.00 is one hundred and sixty-four dollars.

Money

{
  "amount": 164.00,
  "currency": "USD"
}

amount number required: The value.
currency string (ISO 4217) required: Three-letter code, e.g. USD.

Rate

One bookable price for one room. Rates live inside properties[].rooms[].rates[] on a search response.

Rate

{
  "rateKey": "rk_01JD8Q5T6H2V8ZCN4PQ1RMB7XE",
  "rateCode": "BAR_USD",
  "rateName": "Best Available Rate",
  "board": "RO",
  "price": { "net": 150.00, "sell": 164.00, "currency": "USD", "binding": false },
  "nightly": [
    { "date": "2026-12-05", "amount": 82.00 },
    { "date": "2026-12-06", "amount": 82.00 }
  ],
  "taxesAndFees": [
    { "name": "City tax", "amount": 4.00, "included": false, "payAtHotel": true }
  ],
  "refundable": true,
  "cancelPolicy": [ /* … */ ],
  "paymentType": "PREPAID",
  "remarks": "Check-in from 14:00."
}

rateKey string optional: Opaque, single-use handle, valid ~30 minutes. The only thing booking needs to identify the rate.
rateCode string optional: The rate plan’s code.
rateName string optional: A human-readable rate name.
board Board optional: Meal plan — see the board codes below.
price.net number optional: What Gateway Stream pays the supplier. For reconciliation, not display.
price.sell number optional: Your price, markup applied. Display this one.
price.currency string optional: Currency of both figures.
price.binding boolean optional: true when the supplier guarantees the gross price. A binding rate is never marked down below its quoted gross.
nightly { date, amount }[] optional: Per-night breakdown. May be empty.
taxesAndFees { name, amount, included, payAtHotel }[] optional: included: false means it is on top of the rate; payAtHotel: true means the hotel collects it and it is not part of price.sell.
refundable boolean optional: Whether any cancellation window exists. The detail is in cancelPolicy.
cancelPolicy CancelPolicyEntry[] optional: The cancellation ladder. See below.
paymentType "PREPAID" | "PAY_AT_HOTEL" optional: Who collects the room charge.
remarks string optional: Free text from the supplier, when there is any.

Room

roomCode string optional: The room’s code. A property’s room list and its search results use the same codes.
roomName string optional: A human-readable room name.
occupancyRef integer optional: Which entry of the search’s rooms array this room answers, counting from 0.
rates Rate[] optional: The bookable rates for this room.

Property Result

What a search returns per hotel. (The leaner object on GET /properties is documented there.)

propertyId uuid optional: The Gateway Stream property id.
name string optional: Hotel name.
stars number | null optional: Star rating, when known.
location { city, country, lat, lng } optional: Each member may be null.
image string | null optional: A representative photo URL.
mapped boolean optional: Whether this hotel is matched to a Gateway Stream master record.
fromPrice Money | null optional: The cheapest rate on the property, for a “from” price in a list.
rooms Room[] optional: The rooms that returned rates.

A cancellation ladder is a list of these, in ascending order of from. Each entry means: from this moment until check-in, cancelling costs this much. The rung in force is the last one already passed; if none has passed, or the list is empty, cancellation is free as far as the recorded policy goes.

cancelPolicy

[
  { "from": "2026-11-30T00:00:00Z", "amount": 82.00,  "currency": "USD" },
  { "from": "2026-12-04T00:00:00Z", "amount": 164.00, "currency": "USD" }
]

from string (ISO 8601 with offset) required: When this penalty starts to apply.
amount number required: The fee from that moment.
currency string (ISO 4217) required: Currency of the fee.

Destination

A country or a city, from GET /destinations.

type "country" | "city" optional: What kind of place this is.
label string optional: Ready to show: Harare, Zimbabwe, Springfield, IL, United States.
city string | null optional: The city. null on a country.
region string | null optional: A state or province that tells apart cities with the same name.
country string optional: ISO-3166 alpha-2 code — what destination.country on search takes.
countryName string optional: The English name.

Property Detail

What GET /properties/{id} returns: the property fields above, plus the following.

rooms PropertyRoom[] optional: The hotel’s room types, each with its pictures and, for a stay, its rates.
stay { checkIn, checkOut, nights, adults, childAges } | null optional: The stay the rates are for. null when none was asked for.
fromPrice Money | null optional: The cheapest rate. null without a stay, or when nothing is offered.
meta.complete boolean optional: false when a source did not answer, so rooms, pictures or rates may be missing.

PropertyRoom

roomCode string optional: The room’s code.
roomName string | null optional: The room’s name.
images string[] optional: Picture URLs, best first. Empty when there are none.
rates Rate[] optional: The room’s rates for the requested stay. Empty without a stay, or when the room is not offered.

BookedRoom

One entry of rooms on a booking.

roomCode string | null optional: The room’s code.
roomName string | null optional: The room’s name.
guests { title?, name: { first, last }, age? }[] optional: Who is in the room, as sent at book time.
price Money optional: What this room cost.
rate BookedRate | null optional: A Rate as it was sold, without rateKey and price (the key is spent, and the price is on the room). null on a booking made before rates were kept.

Booking

Returned by POST /bookings and GET /bookings/:id.

mode "sandbox" | "live" optional: Which environment the booking lives in.
bookingId uuid optional: The booking id.
status BookingStatus optional: See the enum below.
clientReference string | null optional: Your own reference, if you sent one.
checkIn / checkOut string (YYYY-MM-DD) optional: Stay dates.
nights integer optional: The length of the stay.
property Property | null optional: The hotel booked.
rooms BookedRoom[] optional: One entry per room: its guests, its price and the rate it was sold at.
price Money optional: The booked total.
cancelPolicy CancelPolicyEntry[] optional: The ladder recorded at book time.
hotelConfirmationNumber string | null optional: The hotel’s own reference, when supplied.
createdAt string (ISO 8601) optional: When the booking was created.

Board Codes

RO Room only No meals included.

BB Bed & breakfast Breakfast included.

HB Half board Breakfast and one other meal.

FB Full board Three meals a day.

AI All inclusive Meals and (usually) drinks.

Payment Type

PREPAID — the room charge is settled through Gateway Stream rather than at the hotel.
PAY_AT_HOTEL — the guest settles the room charge with the hotel directly.

Booking Status

PENDING Created, nothing attempted yet.

PAYMENT_PENDING Waiting on payment capture at your end.

PAYMENT_OK Payment recorded; the supplier has not been called yet.

SUPPLIER_BOOKING The supplier call is in flight.

CONFIRMED The supplier confirmed the reservation.

ON_REQUEST The supplier took the request but has not confirmed. Not guaranteed.

FAILED The supplier refused. Nothing is reserved.

UNKNOWN No definite answer. The reservation may or may not exist — reconcile, never retry.

CANCEL_REQUESTED A cancel went out and came back ambiguous. Neither cancelled nor live.

CANCELLED Definitely cancelled.

Result Completeness

Carried by search, property listing and single-property responses as meta. It says only whether the answer is whole — never which source was slow, or why.

meta.complete boolean optional: true when every source answered. false when at least one did not answer in time or failed: what came back is real, but some results may be missing.