Skip to content

Getting Started

This guide walks you through authenticating with a Client Account API key and making your first availability check and booking via the RateNet GraphQL API.

Prerequisites:

  • A Client Account API key provided by your tenant admin
  • The GraphQL endpoint URL for your RateNet instance (e.g. https://ratenet.example.com/graphql)

Step 1 — Authenticate

All requests are authenticated by passing your Client Account API key in the X-API-Key header. There is no login step — include the key on every request:

POST /graphql HTTP/1.1
X-API-Key: rn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Your tenant admin creates the Client Account and provides you with the key. The key is shown only once at creation — if it is lost, ask your admin to rotate it via rollApiKey.

Step 2 — Check hotel availability

Use checkHotels to query availability for one or more specific hotel codes. This hits suppliers directly — no cache, results are 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
        nonrefundable
        cancellationPolicies {
          deadline
          amount
        }
      }
    }
  }
}

Hotels with no availability are returned with an empty rates array. Each rate has a rateKey that you will use in the next steps.

Tip

Rate keys have a limited lifetime — use them promptly. The expiresAt field on each hotel indicates when the results should be considered stale.

Step 3 — Validate the rate

Before booking, call checkRate to confirm the rate is still available at the quoted price. This re-checks with the supplier in real time.

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

Use the rateKey from checkRate, not from search

The rateKey returned by checkRate is what you must pass to bookRate. Rates can be amended between search and validation; always book with the validated key.

Step 4 — Book the rate

Submit the booking with the validated rateKey, occupant details, and lead holder 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: "MY-REF-001"
  }) {
    booking {
      bookingRef
      status
      total
      currency
    }
  }
}

A successful response returns a bookingRef (e.g. RN-12345) and a status of confirmed or pending.

Step 5 — Check or cancel the booking

Retrieve a booking status at any time:

query {
  checkBooking(bookingRef: "RN-12345") {
    bookingRef
    status
    holderName
    hotelName
    checkin
    checkout
    total
    currency
    cancelled
  }
}

To cancel:

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

Next steps