Skip to content

GraphQL Reference — Client Hotel Booking API

All operations are sent as POST /graphql with Content-Type: application/json and X-API-Key: <client-account-key>. See Authentication for details.

This reference covers only the operations accessible to Client Account API key holders. Tenant administration operations (user management, supplier config, contracts, etc.) are outside the scope of this API.

Queries

checkHotels

Synchronous availability check for one or more specific hotels. Hits suppliers directly — no cache, always fresh. This is the primary availability operation for API key integrations.

query {
  checkHotels(input: CheckHotelsInput!) {
    hotels {
      hotelCode
      checkin
      checkout
      currency
      minPrice
      maxPrice
      expiresAt
      rates {
        rateKey
        rate
        currency
        boardType
        boardName
        nonrefundable
        isRefundable
        rooms {
          roomDescription
          numberOfAdults
          childrenAges
        }
        cancellationPolicies {
          deadline
          amount
          currency
        }
      }
    }
  }
}

Input (CheckHotelsInput):

Field Type Required Description
hotelCodes [String!]! Yes One or more supplier hotel codes
checkin String Yes Check-in date (YYYY-MM-DD)
checkout String Yes Check-out date (YYYY-MM-DD)
rooms [RoomInput!]! Yes One entry per room
nationality String Yes ISO 3166-1 alpha-2 country code
currency String No ISO 4217 currency code

Room input:

Field Type Description
adults Int Number of adults
children [{age: Int}] Children with individual ages

Hotels with no availability are returned with an empty rates array. Each rateKey should be treated as opaque and passed to checkRate without modification.

checkRate

Re-validate a rate in real time before booking.

query {
  checkRate(
    rateKey: String!
    isDebug: Boolean
  ) {
    hotel {
      code
      name
      rates {
        rateKey
        boardType
        total
        currency
        nonrefundable
        rooms {
          roomType
          adults
          children
        }
        cancellationPolicies {
          deadline
          amount
        }
      }
    }
  }
}

Always use the rateKey from checkRate

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

booking

Retrieve a single booking by its booking reference.

query {
  booking(bookingRef: String!) {
    bookingRef
    status
    clientRef
    total
    currency
    checkin
    checkout
    holderName
    hotelName
    createdAt
    cancelledAt
  }
}

checkBooking

Booking status lookup. Can be called without authentication when both bookingRef and clientRef are provided — useful for status pages or customer-facing confirmations.

query {
  checkBooking(
    bookingRef: String
    clientRef: String
  ) {
    bookingRef
    status
    holderName
    hotelName
    checkin
    checkout
    total
    currency
    cancelled
  }
}

Mutations

bookRate

Create a booking from a validated rate key.

mutation {
  bookRate(input: BookRateInput!) {
    booking {
      bookingRef
      status
      total
      currency
    }
  }
}

BookRateInput fields:

Field Type Required Description
rateKey String Yes Rate key from checkRate
occupancy [OccupancyInput] Yes One entry per room (see below)
holder HolderInput Yes Lead passenger / booking contact
clientRef String No Your internal reference
specialRequest String No Free-text special request

OccupancyInput:

Field Type Required Description
roomSequence Int Yes 1-based room index matching the availability request
numberOfAdults Int Yes Number of adults in this room
childrenAges [Int] No Ages of children in this room
occupants [OccupantInput] No Named guest details (required by some suppliers)

OccupantInput:

Field Type Required Description
firstname String Yes First name
lastname String Yes Last name
age Int Yes Age
title String No Title (Mr, Mrs, Ms, Dr, etc.)

HolderInput:

Field Type Required Description
firstname String Yes First name
lastname String Yes Last name
email String Yes Contact email
phone String Yes Contact phone number

cancelBooking

Cancel a confirmed booking.

mutation {
  cancelBooking(input: {
    bookingRef: String!
  }) {
    booking {
      bookingRef
      status
      cancelledAt
    }
  }
}

Cancellation charges

Cancellation penalties are determined by the rate's cancellation policy. Retrieve the policy from checkRate or booking before cancelling to avoid unexpected charges.

amendBooking

Amend financial details or remarks on an existing booking.

mutation {
  amendBooking(input: {
    bookingRef: String!
    newTotal: Float
    newCost: Float
    remarks: String
  }) {
    booking {
      bookingRef
      status
      total
    }
  }
}

Error handling

GraphQL errors are returned in the errors array alongside the data object:

{
  "errors": [
    {
      "message": "Rate is no longer available",
      "extensions": {
        "code": "RATE_UNAVAILABLE"
      }
    }
  ]
}

Common error codes:

Code Cause
UNAUTHENTICATED Missing or expired API key
FORBIDDEN Operation is not accessible via Client Account API key
RATE_UNAVAILABLE Rate has expired or sold out between check and book
BOOKING_NOT_FOUND No booking matched the reference
VALIDATION_ERROR Input failed validation (check message for field details)

Synchronous, lean availability check for one or more specific hotels. Hits suppliers directly — no cache, no rich content (images, descriptions, amenities). Designed for B2B API integrations where you already know the hotel codes.

API key clients must use this endpoint

This query is only accessible with an X-API-Key Client Account key. JWT-authenticated (UI) sessions cannot call checkHotels. Use search instead.

query {
  checkHotels(input: CheckHotelsInput!) {
    hotels {
      hotelCode
      checkin
      checkout
      currency
      minPrice
      maxPrice
      expiresAt
      rates {
        rateKey
        rate
        currency
        boardType
        boardName
        nonrefundable
        isRefundable
        rooms {
          roomDescription
          numberOfAdults
          childrenAges
        }
        cancellationPolicies {
          deadline
          amount
          currency
        }
      }
    }
  }
}

Input (CheckHotelsInput):

Field Type Required Description
hotelCodes [String!]! Yes One or more supplier hotel codes
checkin String Yes Check-in date (YYYY-MM-DD)
checkout String Yes Check-out date (YYYY-MM-DD)
rooms [RoomInput!]! Yes One entry per room
nationality String Yes ISO 3166-1 alpha-2 country code
currency String No ISO 4217 currency code

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

search (JWT / UI only)

Search hotel availability for a destination. This is the async, cache-backed search used by the RateNet UI. Returns rich hotel content (images, amenities, descriptions).

Not available to API key clients

Client Account API key requests are rejected with an error. Use checkHotels instead.

query {
  search(input: SearchInputType!) {
    searchID
    total
    page
    pages
    hotels { ... }
  }
}

Input (SearchInputType):

Field Type Required Description
destinationCode String Yes Destination identifier (city or region code)
query.checkin String Yes Check-in date (YYYY-MM-DD)
query.checkout String Yes Check-out date (YYYY-MM-DD)
query.rooms [RoomInput] Yes One entry per room (see below)
query.nationality String Yes ISO 3166-1 alpha-2 country code
query.currency String No ISO 4217 currency code (defaults to operator setting)
filters.sort String No Sort order: price, stars
filters.stars [Int] No Filter by star rating (e.g. [4, 5])
filters.boardTypes [String] No Filter by board type codes (e.g. ["RO", "BB"])
filters.nonrefundable Boolean No Filter out non-refundable rates if false
filters.minPrice Float No Minimum total rate
filters.maxPrice Float No Maximum total rate
filters.ratesPerHotel Int No Max number of rates to return per hotel

Room input:

Field Type Description
adults Int Number of adults
children [{age: Int}] Children with individual ages

Response fields (HotelResult):

Field Description
hotelCode Supplier hotel identifier
name Hotel display name
rates[].rateKey Opaque rate key — pass to checkRate
rates[].rate Displayed price (net cost + margin applied)
rates[].currency Rate currency
rates[].boardType Board type code (e.g. BB, RO, AI)
rates[].nonrefundable Whether the rate is non-refundable
rates[].cancellationPolicies[].deadline Cancellation deadline (datetime)
rates[].cancellationPolicies[].amount Penalty amount if cancelled after deadline

checkRate

Re-validate a rate in real time before booking.

query {
  checkRate(
    rateKey: String!
    isDebug: Boolean
  ) {
    hotel {
      code
      name
      rates {
        rateKey
        boardType
        total
        currency
        nonrefundable
        rooms {
          roomType
          adults
          children
        }
        cancellationPolicies {
          deadline
          amount
        }
      }
    }
  }
}

Rate key changes

The rateKey in the checkRate response may differ from the one in search. Always use the key from checkRate when calling bookRate.

booking

Retrieve a single booking by its booking reference.

query {
  booking(bookingRef: String!) {
    bookingRef
    status
    clientRef
    total
    currency
    checkin
    checkout
    holderName
    hotelName
    createdAt
    cancelledAt
  }
}

bookings

List bookings with optional filters. Requires a tenant_admin or higher role; not accessible via Client Account API key.

query {
  bookings(
    limit: Int
    offset: Int
    status: String
    checkinFrom: String
    checkinTo: String
    clientID: String
  ) {
    total
    items {
      bookingRef
      status
      total
      currency
      checkin
      checkout
      hotelName
      createdAt
    }
  }
}

checkBooking

Public-facing booking status lookup. Can be used without authentication when clientRef is provided alongside bookingRef, or by the booking holder.

query {
  checkBooking(
    bookingRef: String
    clientRef: String
  ) {
    bookingRef
    status
    holderName
    hotelName
    checkin
    checkout
    total
    currency
    cancelled
  }
}

Mutations

login (frontend / UI only)

Exchange user credentials for a JWT token. This is used by the RateNet frontend application and is not the intended auth mechanism for API integrations. Use a Client Account API key instead.

mutation {
  login(input: {
    email: String!
    password: String!
  }) {
    token
    user {
      id
      email
      role
    }
  }
}

bookRate

Create a booking from a validated rate key.

mutation {
  bookRate(input: BookRateInput!) {
    booking {
      bookingRef
      status
      total
      currency
    }
  }
}

BookRateInput fields:

Field Type Required Description
rateKey String Yes Rate key from checkRate
occupancy [OccupancyInput] Yes One entry per room (see below)
holder HolderInput Yes Lead passenger / booking contact
clientRef String No Your internal reference
specialRequest String No Free-text special request

OccupancyInput:

Field Type Required Description
roomSequence Int Yes 1-based room index matching the search request
numberOfAdults Int Yes Number of adults in this room
childrenAges [Int] No Ages of children in this room
occupants [OccupantInput] No Named guest details (required by some suppliers)

OccupantInput:

Field Type Required Description
firstname String Yes First name
lastname String Yes Last name
age Int Yes Age
title String No Title (Mr, Mrs, Ms, Dr, etc.)

HolderInput:

Field Type Required Description
firstname String Yes First name
lastname String Yes Last name
email String Yes Contact email
phone String Yes Contact phone number

cancelBooking

Cancel a confirmed booking.

mutation {
  cancelBooking(input: {
    bookingRef: String!
  }) {
    booking {
      bookingRef
      status
      cancelledAt
    }
  }
}

Cancellation charges

Cancellation penalties are determined by the rate's cancellation policy. Retrieve the policy from checkRate or booking before cancelling to avoid unexpected charges.

amendBooking

Amend financial details or remarks on an existing booking. Requires elevated role (tenant_admin or higher).

mutation {
  amendBooking(input: {
    bookingRef: String!
    newTotal: Float
    newCost: Float
    remarks: String
  }) {
    booking {
      bookingRef
      status
      total
    }
  }
}

Error handling

GraphQL errors are returned in the errors array alongside the data object:

{
  "errors": [
    {
      "message": "Rate is no longer available",
      "extensions": {
        "code": "RATE_UNAVAILABLE"
      }
    }
  ]
}

Common error codes:

Code Cause
UNAUTHENTICATED Missing or expired token
FORBIDDEN Role does not have access to this operation
RATE_UNAVAILABLE Rate has expired or sold out between search and book
BOOKING_NOT_FOUND No booking matched the reference
VALIDATION_ERROR Input failed validation (check message for field details)