Rate Flow

This page documents the complete lifecycle of a hotel booking via the Client Hotel Booking API — from availability check through to cancellation — with exact field names and example request/response payloads.

Overview

1. checkHotels()   →  get available rates for specific hotel codes
2. checkRate()     →  validate rate in real time, get confirmed rateKey
3. bookRate()      →  create the booking, get bookingRef
4. checkBooking()  →  retrieve status (optional, anytime)
5. cancelBooking() →  cancel (if needed)

All operations use POST /graphql with X-API-Key: <client-account-key>.

1. Check Hotels

Fetch available rates for one or more specific hotels. Hits suppliers directly — no cache, always fresh.

query {
  checkHotels(input: {
    hotelCodes: ["HOTEL_CODE_1", "HOTEL_CODE_2"]
    checkin: "2025-08-01"
    checkout: "2025-08-05"
    rooms: [
      { adults: 2, children: [{ age: 8 }] }
    ]
    nationality: "GB"
    currency: "EUR"
  }) {
    hotels {
      hotelCode
      minPrice
      maxPrice
      currency
      expiresAt
      rates {
        rateKey
        rate
        currency
        boardType
        boardName
        nonrefundable
        isRefundable
        rooms {
          roomDescription
          numberOfAdults
          childrenAges
        }
        cancellationPolicies {
          deadline
          amount
          currency
        }
      }
    }
  }
}

Hotels with no availability are returned with an empty rates array.

Rate key format

Each rateKey is a compound opaque string: <queryKey>|<rateKey>, where both parts are base64url-encoded JSON. The queryKey encodes the search parameters (dates, occupancy, nationality, currency). The rateKey encodes supplier-specific identifiers. Treat the entire string as opaque — parse only if instructed by your operator.

2. Check Rate

Validate a specific rate before booking. This re-queries the supplier and returns a fresh rateKey and current cancellation policy.

query {
  checkRate(rateKey: "<rateKey from search>") {
    hotel {
      code
      name
      rates {
        rateKey
        boardType
        total
        currency
        nonrefundable
        rooms {
          roomType
          adults
          children
        }
        cancellationPolicies {
          deadline
          amount
        }
      }
    }
  }
}

Always use the rateKey from checkRate

The key may change between search and checkRate (e.g. supplier-side amendments or supplier rate ID rotation). Pass the rateKey from the checkRate response — not the one from search — to bookRate.

3. Book Rate

Create the booking. You need the validated rateKey, occupant details for each room, and lead holder contact information.

mutation {
  bookRate(input: {
    rateKey: "<rateKey from checkRate>"
    occupancy: [
      {
        roomSequence: 1
        numberOfAdults: 2
        childrenAges: [8]
        occupants: [
          {
            firstname: "Jane"
            lastname: "Smith"
            age: 35
            title: "Ms"
          }
        ]
      }
    ]
    holder: {
      firstname: "Jane"
      lastname: "Smith"
      email: "[email protected]"
      phone: "+441234567890"
    }
    clientRef: "AGENCY-REF-2025-001"
    specialRequest: "High floor if available"
  }) {
    booking {
      bookingRef
      status
      total
      currency
    }
  }
}

Successful response:

{
  "data": {
    "bookRate": {
      "booking": {
        "bookingRef": "RN-78523",
        "status": "confirmed",
        "total": 420.00,
        "currency": "EUR"
      }
    }
  }
}

Booking statuses:

Status	Meaning
`confirmed`	Booking confirmed with the supplier
`pending`	Supplier confirmation in progress (poll `checkBooking`)
`failed`	Booking could not be created
`cancelled`	Booking has been cancelled

4. Check Booking (optional)

Retrieve the current status of a booking at any time. This can be called without authentication when both bookingRef and clientRef are provided.

query {
  checkBooking(
    bookingRef: "RN-78523"
    clientRef: "AGENCY-REF-2025-001"
  ) {
    bookingRef
    status
    holderName
    hotelName
    checkin
    checkout
    total
    currency
    cancelled
  }
}

For authenticated users, bookingRef alone is sufficient:

query {
  booking(bookingRef: "RN-78523") {
    bookingRef
    status
    clientRef
    total
    currency
    checkin
    checkout
    hotelName
    holderName
    createdAt
  }
}

5. Cancel Booking

mutation {
  cancelBooking(input: {
    bookingRef: "RN-78523"
  }) {
    booking {
      bookingRef
      status
      cancelledAt
    }
  }
}

Before cancelling, check the cancellation policy from the booking record to understand any applicable penalty:

query {
  booking(bookingRef: "RN-78523") {
    rates {
      cancellationPolicies {
        deadline
        amount
      }
    }
  }
}

Non-refundable rates

If the rate was booked as nonrefundable: true, a cancellation will typically incur a 100% penalty. Always display the cancellation policy to the end user before confirming a cancellation.

Error scenarios

Scenario	Error	Resolution
Rate sold out between search and book	`RATE_UNAVAILABLE`	Restart from `search`
`rateKey` from `search` used in `bookRate`	`VALIDATION_ERROR`	Always call `checkRate` first
Booking not found	`BOOKING_NOT_FOUND`	Verify the `bookingRef` value
API key expired or revoked	`UNAUTHENTICATED`	Ask your tenant admin to roll the Client Account key