> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.kitionz.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kitionz.com/_mcp/server.

# List bookings

GET https://sandbox-api.kitionz.com/v1/flights/bookings

**List your bookings.**

**What:** your organisation’s bookings, newest first (cursor-paginated via `meta.pagination.nextCursor`). Only the bookings of the environment your key belongs to (Test or Live).

**When:** an itinerary / orders dashboard, or to find a booking whose `/book` answer you never received.

**Filters** (all optional, combined with AND):

* `status` — one status, or repeat the parameter for several (`?status=HELD&status=CONFIRMED`, at most 10): a booking in any of them is listed. Each value must be a known status.
* `supplierCode`, `pnr` (exact airline PNR).
* `externalReference` — exact, case-sensitive match on the reference you sent on `/book`. After a lost `/book` answer, list with it: each row is a booking that carries that reference (Kitionz does not require references to be unique); an empty list means none does.
* `departureFrom` / `departureTo` — the **departure** date (the first flight), `YYYY-MM-DD`, both inclusive. Not the day the booking was made.
* `createdFrom` / `createdTo` — the day the booking was **created**, `YYYY-MM-DD` in India time (IST): 27 October runs from 00:00 to 23:59:59 IST (18:30 UTC on the 26th to 18:30 UTC on the 27th). Both inclusive. Use these for “bookings made today”.

Old names, accepted until the next release, which removes them: `sourceCode` (now `supplierCode`), `fromDate` / `toDate` (now `departureFrom` / `departureTo`). An old and a new name with different values → `400 VALIDATION_ERROR` naming both.
Any other parameter is refused with `400 VALIDATION_ERROR` naming it, so a misspelt filter never returns an unfiltered list. Each row carries `externalReference` (`null` when none was sent).

**Read the new names — the old ones are removed in the next release.** Each new name has the same value as its old one until then, and the reference marks the old name deprecated. Each row: `supplierCode` for `sourceCode`; `origin` / `destination` (`{ iataCode, name, city, countryCode, timezone }`) for `originCode` / `destCode`; `price { totalAmount, currency }` for `totalAmount` / `currency` (the full price block is on `GET /v1/flights/bookings/{id}`).

Reference: https://docs.kitionz.com/flights/list-bookings

## Authentication

- `Authorization` header (bearer token, required) — Your Kitionz API key, sent as `Authorization: Bearer keyId:secret`. Create a Test key at sandbox.kitionz.com → **API keys**, a Live key at kitionz.com → **API → API keys**.

## Servers

- `https://sandbox-api.kitionz.com` (Test, default)
- `https://api.kitionz.com` (Live)

## Request

### Query parameters

- `status` (V1FlightsBookingsGetParametersStatus, optional) — Only bookings in this status. Repeat the parameter for several statuses (`?status=HELD&status=CONFIRMED`, at most 10): a booking in any of them is listed.
- `pnr` (string, optional) — Only bookings with exactly this airline PNR.
- `externalReference` (string, optional) — Only bookings whose `externalReference` (the reference you sent on /book) is exactly this value. Case-sensitive.
- `createdFrom` (string, optional) — Only bookings created on or after this calendar day, YYYY-MM-DD, counted in India time (IST, UTC+05:30): 27 October starts at 00:00 IST, which is 18:30 UTC on 26 October.
- `createdTo` (string, optional) — Only bookings created on or before this calendar day (the whole day, to 23:59:59 IST), YYYY-MM-DD, counted in India time (IST, UTC+05:30).
- `supplierCode` (string, optional) — Only bookings from this supplier (its supplier code).
- `departureFrom` (string, optional) — Only bookings whose DEPARTURE date (the date of the first flight) is on or after this date, YYYY-MM-DD. Not the day the booking was made: use `createdFrom` for that.
- `departureTo` (string, optional) — Only bookings whose DEPARTURE date (the date of the first flight) is on or before this date, YYYY-MM-DD. Not the day the booking was made: use `createdTo` for that.
- `limit` (integer, optional, default: 25)
- `cursor` (string, optional)

## Response

### 200

Default Response

- `success` (boolean, required)
- `statusCode` (double, required)
- `data` (list of FlightBookingListItem, required)
- `meta` (V1FlightsBookingsGetResponsesContentApplicationJsonSchemaMeta, required)

## Types

### V1FlightsBookingsGetParametersStatus

Only bookings in this status. Repeat the parameter for several statuses (`?status=HELD&status=CONFIRMED`, at most 10): a booking in any of them is listed.

- enum
  - Allowed values: `RESERVED`, `PENDING_CONFIRMATION`, `PARTIALLY_BOOKED`, `HELD`, `PENDING_FULFILMENT`, `CONFIRMED`, `FAILED`, `CANCELLED`, `SCHEDULE_CHANGED`, `CANCELLED_BY_SUPPLIER`
- list of enum
  - Allowed values: `RESERVED`, `PENDING_CONFIRMATION`, `PARTIALLY_BOOKED`, `HELD`, `PENDING_FULFILMENT`, `CONFIRMED`, `FAILED`, `CANCELLED`, `SCHEDULE_CHANGED`, `CANCELLED_BY_SUPPLIER`

### FlightBookingListItem

A booking summary row in the bookings list.

- `id` (string, required)
- `supplierCode` (string, required) — The supplier's code.
- `seller` (FlightBookingListItemSeller, required, nullable) — Who sold the booking: its name (website and support contacts are on GET /v1/flights/bookings/\{id}). null when the seller could not be resolved.
- `environment` (enum, required)
  - Allowed values: `SANDBOX`, `PRODUCTION`
- `status` (enum, required) — Booking status. Each booking also carries nextAction, which names what you do next. What each value means: * RESERVED — transient: Kitionz reserved the booking before calling the supplier. Treat it like PENDING\_CONFIRMATION. * PENDING\_CONFIRMATION — not final yet, and the booking MAY exist at the supplier. Do NOT book this trip again and do not issue a ticket to your customer. Read the booking again after nextAction.pollAfterSeconds. Kitionz checks it with the supplier; still pending after 20 minutes: contact Kitionz support with the booking id. * PARTIALLY\_BOOKED — no longer produced: Kitionz never books a round trip as two separate bookings. Listed until a later version removes it. * HELD — the seats are held, not ticketed. Ticket before nextAction.deadlineAt with POST /v1/flights/bookings/\{id}/ticket. * PENDING\_FULFILMENT — a request: nothing is booked and nothing charged by Kitionz. Book on the supplier’s portal, then POST /v1/flights/bookings/\{id}/fulfil with the PNR before nextAction.deadlineAt (72 hours after booking by default, or the first flight’s departure if that is earlier), or /cancel to withdraw. After the deadline Kitionz may cancel the request at any time. * CONFIRMED — booked and confirmed; pnr is present. * FAILED — not booked, nothing charged; failure says why. Safe to search and book again. * CANCELLED — cancelled or withdrawn (including an expired request). * SCHEDULE\_CHANGED — not produced today: Kitionz does not watch confirmed bookings for airline changes and sends no webhook for them. Airline and seller messages reach your organisation’s registered email and mobile; to catch a change, watch each booked flight with Flight Status (POST /v1/flight-status/monitors) and refresh the booking before departure. * CANCELLED\_BY\_SUPPLIER — the seller reported the booking cancelled when Kitionz read it: after you call POST /v1/flights/bookings/\{id}/refresh, or while Kitionz checks a pending booking. Kitionz does not read confirmed bookings by itself and sends no webhook for this. Contact the seller named in seller.
  - Allowed values: `RESERVED`, `PENDING_CONFIRMATION`, `PARTIALLY_BOOKED`, `HELD`, `PENDING_FULFILMENT`, `CONFIRMED`, `FAILED`, `CANCELLED`, `SCHEDULE_CHANGED`, `CANCELLED_BY_SUPPLIER`
- `bookingMode` (string, required)
- `bookingChannel` (enum, required, nullable)
  - Allowed values: `CONSOLE_UI`, `API`
- `supplierReference` (string, required, nullable)
- `pnr` (string, required, nullable)
- `origin` (FlightBookingListItemOrigin, required) — Where the trip starts.
- `destination` (FlightBookingListItemDestination, required) — Where the outbound trip ends.
- `departureDate` (string, required, nullable)
- `returnDate` (string, required, nullable)
- `adults` (double, required)
- `children` (double, required)
- `infants` (double, required)
- `price` (FlightBookingListItemPrice, required) — The booking’s total and currency. The full price block is on GET /v1/flights/bookings/\{id}.
- `externalReference` (string, required, nullable)
- `bookedAt` (string, required)
- `sourceCode` (string, required, deprecated) — Old name of supplierCode (the same value), removed in the next release. Read supplierCode.
- `supplierName` (string, required, nullable, deprecated) — Old name of seller.name (the same value), removed in the next release. Read seller.name.
- `originCode` (string, required, deprecated) — Old name of origin.iataCode (the same value), removed in the next release. Read origin.iataCode.
- `destCode` (string, required, deprecated) — Old name of destination.iataCode (the same value), removed in the next release. Read destination.iataCode.
- `totalAmount` (double, required, deprecated) — Old name of price.totalAmount (the same value), removed in the next release. Read price.totalAmount.
- `currency` (string, required, deprecated) — Old name of price.currency (the same value), removed in the next release. Read price.currency.

### V1FlightsBookingsGetResponsesContentApplicationJsonSchemaMeta

- `requestId` (string, required)
- `timestamp` (datetime, required)
- `path` (string, required)
- `method` (string, required)
- `responseTime` (double, optional)
- `pagination` (V1FlightsBookingsGetResponsesContentApplicationJsonSchemaMetaPagination, optional)

### FlightBookingListItemSeller

Who sold the booking: its name (website and support contacts are on GET /v1/flights/bookings/\{id}). null when the seller could not be resolved.

- `name` (string, required, nullable)

### FlightBookingListItemOrigin

Where the trip starts.

- `iataCode` (string, required) — IATA airport code.
- `name` (string, required, nullable) — Airport name from the Kitionz airport list; null when the airport is not in it (the same rule on offers, bookings and stops).
- `city` (string, required, nullable) — The city the airport serves; null when the airport is not in the Kitionz airport list.
- `countryCode` (string, required, nullable) — ISO 3166-1 alpha-2 country code; null when the airport is not in the Kitionz airport list.
- `timezone` (string, required, nullable) — IANA time zone (the flight's local times carry its offset); null when the airport is not in the Kitionz airport list.

### FlightBookingListItemDestination

Where the outbound trip ends.

- `iataCode` (string, required) — IATA airport code.
- `name` (string, required, nullable) — Airport name from the Kitionz airport list; null when the airport is not in it (the same rule on offers, bookings and stops).
- `city` (string, required, nullable) — The city the airport serves; null when the airport is not in the Kitionz airport list.
- `countryCode` (string, required, nullable) — ISO 3166-1 alpha-2 country code; null when the airport is not in the Kitionz airport list.
- `timezone` (string, required, nullable) — IANA time zone (the flight's local times carry its offset); null when the airport is not in the Kitionz airport list.

### FlightBookingListItemPrice

The booking’s total and currency. The full price block is on GET /v1/flights/bookings/\{id}.

- `totalAmount` (double, required) — What you pay the seller, in INR, for the passengers it priced. When infantFare.status is NOT_GIVEN it covers adults and children only.
- `currency` (string, required)

### V1FlightsBookingsGetResponsesContentApplicationJsonSchemaMetaPagination

- `page` (double, optional)
- `limit` (double, optional)
- `total` (double, optional)
- `totalPages` (double, optional)
- `hasNext` (boolean, optional)
- `hasPrev` (boolean, optional)

## Examples

**Response**

```json
{
  "success": true,
  "statusCode": 200,
  "data": [
    {
      "id": "bkg_034nVJSoVy7WgMmcQvWHJA",
      "supplierCode": "kitionz_test_air",
      "seller": {
        "name": "Kitionz Test Air"
      },
      "environment": "SANDBOX",
      "status": "FAILED",
      "bookingMode": "LIVE",
      "bookingChannel": "API",
      "supplierReference": null,
      "pnr": null,
      "origin": {
        "iataCode": "DEL",
        "name": "Indira Gandhi International Airport",
        "city": "New Delhi",
        "countryCode": "IN",
        "timezone": "Asia/Kolkata"
      },
      "destination": {
        "iataCode": "BOM",
        "name": "Chhatrapati Shivaji Maharaj International Airport",
        "city": "Mumbai",
        "countryCode": "IN",
        "timezone": "Asia/Kolkata"
      },
      "departureDate": "2026-11-30",
      "returnDate": null,
      "adults": 1,
      "children": 0,
      "infants": 0,
      "price": {
        "totalAmount": 5824,
        "currency": "INR"
      },
      "externalReference": null,
      "bookedAt": "2026-10-28T02:02:18.973Z",
      "sourceCode": "kitionz_test_air",
      "supplierName": "Kitionz Test Air",
      "originCode": "DEL",
      "destCode": "BOM",
      "totalAmount": 5824,
      "currency": "INR"
    },
    {
      "id": "bkg_034nVJSR1PGFZYW9sYEu7h",
      "supplierCode": "kitionz_test_air",
      "seller": {
        "name": "Kitionz Test Air"
      },
      "environment": "SANDBOX",
      "status": "CONFIRMED",
      "bookingMode": "LIVE",
      "bookingChannel": "API",
      "supplierReference": "SIM-CONFIRM-1793152938-ASG179D0LO",
      "pnr": "TESTERYVTQ",
      "origin": {
        "iataCode": "DEL",
        "name": "Indira Gandhi International Airport",
        "city": "New Delhi",
        "countryCode": "IN",
        "timezone": "Asia/Kolkata"
      },
      "destination": {
        "iataCode": "BOM",
        "name": "Chhatrapati Shivaji Maharaj International Airport",
        "city": "Mumbai",
        "countryCode": "IN",
        "timezone": "Asia/Kolkata"
      },
      "departureDate": "2026-11-30",
      "returnDate": null,
      "adults": 1,
      "children": 0,
      "infants": 0,
      "price": {
        "totalAmount": 5324,
        "currency": "INR"
      },
      "externalReference": null,
      "bookedAt": "2026-10-28T02:02:18.759Z",
      "sourceCode": "kitionz_test_air",
      "supplierName": "Kitionz Test Air",
      "originCode": "DEL",
      "destCode": "BOM",
      "totalAmount": 5324,
      "currency": "INR"
    },
    {
      "id": "bkg_034nQsv3caLshneFj9bFur",
      "supplierCode": "kitionz_test_portal",
      "seller": {
        "name": "Kitionz Test Air"
      },
      "environment": "SANDBOX",
      "status": "CONFIRMED",
      "bookingMode": "REQUEST",
      "bookingChannel": "API",
      "supplierReference": "TESTA7K2Q9",
      "pnr": "TESTA7K2Q9",
      "origin": {
        "iataCode": "DEL",
        "name": "Indira Gandhi International Airport",
        "city": "New Delhi",
        "countryCode": "IN",
        "timezone": "Asia/Kolkata"
      },
      "destination": {
        "iataCode": "BOM",
        "name": "Chhatrapati Shivaji Maharaj International Airport",
        "city": "Mumbai",
        "countryCode": "IN",
        "timezone": "Asia/Kolkata"
      },
      "departureDate": "2026-11-30",
      "returnDate": null,
      "adults": 1,
      "children": 0,
      "infants": 0,
      "price": {
        "totalAmount": 5324,
        "currency": "INR"
      },
      "externalReference": null,
      "bookedAt": "2026-10-27T23:01:52.745Z",
      "sourceCode": "kitionz_test_portal",
      "supplierName": "Kitionz Test Air",
      "originCode": "DEL",
      "destCode": "BOM",
      "totalAmount": 5324,
      "currency": "INR"
    }
  ],
  "meta": {
    "requestId": "req_034nVJSvKzDjwAXM0IS47s",
    "timestamp": "2026-10-28T02:02:19.104Z",
    "path": "/v1/flights/bookings?limit=3",
    "method": "GET",
    "pagination": {
      "limit": 3,
      "mechanism": "cursor",
      "nextCursor": "MjAyNi0xMC0yN1QyMzowMTo1Mi43NDVafGJrZ18wMzRuUXN2M2NhTHNobmVGajliRnVy"
    }
  }
}
```

**SDK Code**

```python
import requests

url = "https://sandbox-api.kitionz.com/v1/flights/bookings"

querystring = {"limit":"3"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://sandbox-api.kitionz.com/v1/flights/bookings?limit=3';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox-api.kitionz.com/v1/flights/bookings?limit=3"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://sandbox-api.kitionz.com/v1/flights/bookings?limit=3")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://sandbox-api.kitionz.com/v1/flights/bookings?limit=3")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://sandbox-api.kitionz.com/v1/flights/bookings?limit=3', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://sandbox-api.kitionz.com/v1/flights/bookings?limit=3");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://sandbox-api.kitionz.com/v1/flights/bookings?limit=3")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```