6 · Book

Place a booking.

What: places the booking. Requires the quoteToken from /fare-quote; the supplier-quoted price is taken from the signed token, so a tenant can’t book a different price than was quoted.

When: after a successful /fare-quote, within the token’s validity.

Before / After: /fare-quote → here → read the booking’s status (and /bookings/{id}/ticket if it is HELD).

Gotchas

• Send the offer’s trip back — tripType, departureDate and (round trip) returnDate — exactly as on /fare-quote (the token binds them).
• Idempotency is the Idempotency-Key HEADER (required). Persist it and reuse the same value on retries — the booking is reserved before the supplier call, so a retry returns the same booking instead of charging twice. There is no body idempotency field.
• passengers[].travelerType is ADULT / CHILD / INFANT, and the array must match adults/children/infants. A CHILD or INFANT needs dateOfBirth; every INFANT needs a guardian (the travelling adult’s name).
• If /book is slow or your request times out, never book again with a new key. If you got a booking back, read its status (PENDING_CONFIRMATION means wait: read GET /bookings/{id} every 30 seconds). If you got no answer, send the identical request again with the SAME Idempotency-Key: you get the first booking back, or 409 BOOKING_IN_PROGRESS / IDEMPOTENT_REQUEST_IN_PROGRESS while it is still running (wait, then send it again).
• An answer with no Kitionz error.code (for example a 504 from the network) or any 500 counts as no answer: send the same request again with the same key. Set your HTTP timeout for /book to at least 90 seconds; a slow supplier can take more than a minute.
• Just before booking, Kitionz asks the supplier for the fare again and checks it the same way as /fare-quote. A broken answer → 422 FARE_QUOTE_UNUSABLE. An infant price that changed since your quote → 409 FARE_RECHECK_FAILED: failureClass INFANT_PRICE_WITHDRAWN (you were quoted one, the supplier gives none now; quote again: it shows NOT_GIVEN) or INFANT_PRICE_APPEARED (you were quoted NOT_GIVEN, the supplier gives one now; quote again: it shows PRICED). All are definite: nothing was booked or charged.
• You never send an amount. When the quote said infantFare.status: NOT_GIVEN, the booking is made at the supplier’s total (adults and children) and your own infant charge stays with you. The booking’s fareBreakdown.infantFare is the supplier’s statement when the booking was made; since /book refuses any change from the quote, it is always the status you were quoted.

Example — request (with the Idempotency-Key: <your-uuid> header):

{
  "supplierOfferRef": "floffer_9x2k7q",
  "quoteToken": "eyJhbGci…",
  "adults": 1, "tripType": "ONE_WAY", "departureDate": "2027-01-15",
  "originCode": "DEL", "destCode": "BOM",
  "booker": { "name": "Asha Rao", "email": "asha@example.com", "phone": "+919800000000" },
  "passengers": [ { "title": "Ms", "firstName": "Asha", "lastName": "Rao", "travelerType": "ADULT" } ]
}

Response (trimmed) — the HTTP status is 201; decide by data.status:

{ "data": { "id": "bkg_7f3a92", "status": "CONFIRMED", "pnr": "AB12CD", "supplier": { "name": "Airnatt Holidays", "website": "https://airnatt.com", "supportPhone": "+91 99999 00000", "supportEmail": "help@airnatt.com" }, "returnSupplier": null } }

supplier names who sold the flight (the real seller behind a marketplace), with the support contacts Kitionz holds — on every booking from the moment it exists. returnSupplier is always null (one seller per booking); it will be removed in a later version.