Get Booking

Takes the bookingId returned by POST /bookings. The response is the same booking view that booking returned, with status reflecting wherever the reservation has got to since.

curl https://api.gatewaystream.com/api/v1/bookings/0b5e1a92-6c3f-4a7d-8e21-9b4f0d3c5a18 \
  -H "x-api-key: $GWS_KEY"

{
  "mode": "sandbox",
  "bookingId": "0b5e1a92-6c3f-4a7d-8e21-9b4f0d3c5a18",
  "status": "CONFIRMED",
  "clientReference": "ACME-2026-00417",
  "checkIn": "2026-12-05",
  "checkOut": "2026-12-07",
  "nights": 2,
  "property": {
    "propertyId": "a9702286-9b22-498d-8bc9-97471f68d798",
    "name": "Kadoma Hotel & Conference Centre",
    "stars": 4,
    "country": "Zimbabwe",
    "city": "Kadoma",
    "image": "https://cdn.gatewaystream.com/properties/kadoma/exterior.jpg"
  },
  "rooms": [
    {
      "roomCode": "DBL-STD",
      "roomName": "Double Standard",
      "guests": [
        { "name": { "first": "Test", "last": "Guest" }, "age": 30 }
      ],
      "price": { "amount": 164.00, "currency": "USD" },
      "rate": {
        "rateCode": "BAR_USD",
        "rateName": "Best Available Rate",
        "board": "RO",
        "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": [
          { "from": "2026-11-30T00:00:00Z", "amount": 82.00, "currency": "USD" },
          { "from": "2026-12-04T00:00:00Z", "amount": 164.00, "currency": "USD" }
        ],
        "paymentType": "PREPAID",
        "remarks": "Check-in from 14:00."
      }
    }
  ],
  "price": { "amount": 164.00, "currency": "USD" },
  "cancelPolicy": [
    { "from": "2026-11-30T00:00:00Z", "amount": 82.00, "currency": "USD" },
    { "from": "2026-12-04T00:00:00Z", "amount": 164.00, "currency": "USD" }
  ],
  "hotelConfirmationNumber": "KHC-558213",
  "createdAt": "2026-11-02T09:41:07.221Z"
}

Fields#

mode

"sandbox" | "live" optional

Which environment this booking lives in.

bookingId

uuid optional

The booking’s own id.

status

BookingStatus optional

Where the reservation stands. See the status enum for every value.

clientReference

string | null optional

The reference.client sent at book time.

checkIn / checkOut

string (YYYY-MM-DD) optional

The stay dates.

nights

integer optional

The length of the stay.

property

object | null optional

The hotel booked: propertyId, name, stars, city, country and image.

rooms

object[] optional

One entry per room: roomCode, roomName, guests, the room’s price and the rate it was sold at (board, nightly prices, taxes, refundability, its own cancelPolicy and paymentType). rate is null on a booking made before rates were kept with it. The field-by-field shape is on Book.

price

{ amount, currency } optional

The booked total.

cancelPolicy

object[] optional

The cancellation ladder recorded at book time: { from, amount, currency } entries, each meaning “from this moment onwards, cancelling costs this much”.

hotelConfirmationNumber

string | null optional

The hotel’s own reference, when the supplier provided one.

createdAt

string (ISO 8601) optional

When the booking was created.

Reading the Cancellation Ladder#

cancelPolicy is a list of deadlines in ascending order. Each entry says: from this moment until check-in, cancelling costs this amount. 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 is concerned.

So a ladder of 2026-11-30 → 82.00 and 2026-12-04 → 164.00 means: free until 30 November, 82.00 from then until 4 December, and the full 164.00 after that.

Status Codes#

200

The booking, as it stands.

400 validation_error

The id in the path is not a valid uuid.

401 unauthorized

Missing or invalid x-api-key.

404 not_found

No such booking for this key. Another client’s booking answers exactly the same way as one that never existed.

{
  "error": {
    "code": "not_found",
    "message": "Booking '0b5e1a92-6c3f-4a7d-8e21-9b4f0d3c5a18' was not found",
    "requestId": "req_01JD8QF5N3X8D2KM"
  }
}

Polling#

A booking that came back ON_REQUEST or UNKNOWN can change without you doing anything. Poll gently — every few minutes, not every few seconds — and remember the rate limit applies to this endpoint like any other.