The booking flow

At a glanceCopy Anchor Link

Before you startCopy Anchor Link

Every request carries the same three headers. The token comes from Authentication. It is a custom header, not Authorization: Bearer.

Three clocks run during a flowCopy Anchor Link

Every response restarts the key clock. When anything expires, start again from Quote with a fresh token.

Step by stepCopy Anchor Link

1. QuoteCopy Anchor Link

Search by one of these: a list of up to 3,000 hotel codes that lie within about 200 km of each other, or a destinationId such as MAD. One 3,000-code call beats many small ones. Docs

• Each distributions[] entry is one room. Each person has an age. Send each guest's age at checkout, because Prebook will check it.
• tripType and filter are optional: without them you get a hotel-only search (ONLY_HOTEL) with the default filter. Confirmed The samples send tripType anyway, because an explicit request is easier to read in your logs.
• A stay can be at most 30 nights (checkOut minus checkIn). A longer one gets 400. Tested
• timeout is in milliseconds, at least 3000; send null or leave it out for your account's default. Tested Set your HTTP timeout well above it: quotes can take 18 seconds or more. Docs
• Prices and cancellation policies here are informational. Only Confirm guarantees them.

Quote reference

2. Quote single (optional)Copy Anchor Link

Returns every room combination for one hotel. Use it when Quote marked a hotel quoteSingleNeeded: true, or when the guest starts from a hotel page. quoteSingleNeeded does not mean "not bookable": the combinations you already have are bookable, there are simply more. Never call Quote single in parallel for many hotels; use Quote with a code list instead. Docs

Quote single reference

3. ConfirmCopy Anchor Link

The first authoritative price and cancellation policy. The response also tells you which guest data to collect.

• warnings[] can contain PRICE_CHANGE or CANCELLATION_POLICIES_CHANGE. Show them and get the guest's consent again.
• requiredField lists the passenger fields Prebook needs: title, names, document, email, phone and so on. See Rooms and guests.

Confirm reference

4. PrebookCopy Anchor Link

Sends guest details and re-validates the offer with the supplier.

• Repeat the quote's rooms in the same order, with the same number of people in each.
• requestedAge is mandatory and is the age at the end of the stay. It must equal the quoted age. Docs
• Names must be in Latin script. Transliterate Arabic, Cyrillic or CJK names first. Spec
• Compare price, meal plan and cancellation policies with Confirm before you call Book.

Prebook reference

5. BookCopy Anchor Link

Closes the booking. A 200 response is not a confirmation: branch on status, and never retry Book automatically. Save your externalReference before you call it.

Book reference

Full exampleCopy Anchor Link

The same flow end to end. Credentials come from environment variables, the token is checked once before Quote, and auditData.authToken is removed before anything is logged.

// One token and one flow. combinationKeys never leave your server.
const BASE = process.env.NAVA_BASE_URL!; // e.g. https://nava.travel/resources

export async function bookHotel(search: QuoteRequest, guests: Distribution[], orderId: string) {
  const token = await getToken({ minMinutesLeft: 60 }); // never refreshed mid-flow

  // 1. Quote
  const quote = await post(token, '/booking/accommodations/quote', {
    tripType: 'ONLY_HOTEL',
    ...search,
  });
  const hotel = quote.accommodations[0];
  let key = hotel.combinations[0].combinationKey; // key 1

  // 3. Confirm: authoritative price and cancellation policies
  const confirm = await post(token, `/booking/accommodations/${hotel.code}/confirm`, {
    accommodation: { combinationKey: key },
  });
  if (confirm.warnings?.length) await askGuestToAccept(confirm.warnings);
  key = confirm.accommodation.combination.combinationKey; // key 2

  // 4. Prebook: same rooms, same order, ages at the end of the stay
  const prebook = await post(token, `/booking/accommodations/${hotel.code}/prebook`, {
    accommodation: { combinationKey: key },
    distributions: guests,
  });
  assertSameOffer(confirm, prebook); // price, meal plan, cancellation policies
  key = prebook.accommodation.combination.combinationKey; // key 3

  // 5. Book: called once, never retried
  await saveOrder(orderId);
  const booked = await post(token, `/booking/accommodations/${hotel.code}/book`, {
    accommodation: { combinationKey: key },
    externalReference: orderId,
  });
  return handleBookStatus(booked);
}

async function post(token: string, path: string, body: unknown) {
  const res = await fetch(BASE + path, {
    method: 'POST',
    headers: {
      'auth-token': token,
      'Accept-Encoding': 'gzip',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  });
  const json = await res.json();
  if (json?.auditData?.authToken) json.auditData.authToken = '[REDACTED]';
  log(path, res.status, json.auditData?.traceId);
  if (!res.ok) throw new ApiError(res.status, json);
  return json;
}