BookingClub Inner API v1

Authentication

Every API request uses a client API key. Demo keys create demo bookings. Live keys create normal operational bookings.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

God Mode can set scopes, allowed IPs, logging mode, request limits, billing mode, request cost and API commission per key.

Common Rules

Rule	Details
Response format	All responses are JSON: `success`, `requestId`, `data`, `errors`.
Dates	Use `YYYY-MM-DD`.
Currency	Any endpoint returning a new price requires `currency`. Booking detail, cancel quote and cancel return the original booking currency and do not accept currency.
Nationality	`nationalityId` is optional. Use `GET /reference/nationalities` to list values.
Children	Send `childrenAges` only when there are children. If children exist, ages are required and must match booking guests.
Idempotency	Write endpoints require `Idempotency-Key`. Retrying the exact same request with the same key returns the saved response without creating a duplicate booking.
Visibility	Products include supervisor internal contracts, enabled TL/TL2 products and WTX products visible to the supervisor.
Billing	God Mode request billing counts successful requests. Depending on key settings, requests may be free, per-request paid, or monthly quota plus paid extra.

Simulator

Requests are sent directly from this browser to https://api.bookingclub.net/v1. The API key is not saved by this page.

API key

Template

Method

Path

Idempotency-Key

JSON body

{}

Reference Data

Endpoint	Query	Scope
GET `/reference/countries`	`q`, `language`, `page`, `limit`	`reference:read`
GET `/reference/regions`	`countryId`, `q`, `language`, `page`, `limit`	`reference:read`
GET `/reference/cities`	`countryId`, `regionId`, `q`, `language`, `page`, `limit`	`reference:read`
GET `/reference/airports`	`countryId`, `regionId`, `cityId`, `q`, `language`, `page`, `limit`	`reference:read`
GET `/reference/currencies`	`q`, `page`, `limit`	`reference:read`
GET `/reference/currency-rates`	None	`reference:read`
GET `/reference/nationalities`	`q`, `page`, `limit`	`reference:read`
GET `/reference/languages`	`q`, `language`, `page`, `limit`	`reference:read`
GET `/reference/meal-plans`	`q`, `page`, `limit`	`reference:read`

Properties

Endpoint	Required	Optional	Scope
GET `/properties`	None	`q`, `countryId`, `cityId`, `source`, `page`, `limit`	`properties:read`
GET `/properties/{propertyId}`	`propertyId`	None	`properties:read`

A propertyId may represent an internal hotel, TL/TL2 hotel, or WTX product. Use the returned ID exactly as received.

Hotel Availability

POST /hotels/availability requires scope availability:read.

Field	Required	Details
`propertyId`	Yes	Use ID from `/properties`.
`checkIn`, `checkOut`	Yes	`checkOut` must be after `checkIn`.
`currency`	Yes	Required because prices are returned.
`rooms[].adults`	Yes	Adult count per room.
`rooms[].childrenAges`	No	Required only when children are present.
`nationalityId`	No	Optional nationality.

{
  "propertyId": "24",
  "checkIn": "2026-06-20",
  "checkOut": "2026-06-21",
  "currency": "USD",
  "nationalityId": 1,
  "rooms": [
    {"adults": 2, "childrenAges": []}
  ]
}

Tours

Endpoint	Required	Optional	Scope
GET `/tours`	None	`q`, `countryId`, `cityId`, `page`, `limit`	`tours:read`
GET `/tours/{tourId}`	`tourId`	None	`tours:read`
POST `/tours/availability`	`tourId`, `checkIn`, `checkOut`, `currency`, `adults`	`childrenAges`, `vehicleId`, `languageId`, `nationalityId`	`availability:read`

Transfers

Endpoint	Required	Optional	Scope
GET `/transfers`	None	`q`, `countryId`, `cityId`, `page`, `limit`	`transfers:read`
GET `/transfers/{transferId}`	`transferId`	None	`transfers:read`
POST `/transfers/availability`	`transferKind`, `checkIn`, `currency`, `adults`, route fields	`transferId`, `vehicleId`, `childrenAges`, `nationalityId`, `flightNumber`, `time`, hotel IDs	`availability:read`

transferKind	Required route fields
`1` arrival	`pickupAirportId`, `dropOffCityId`
`2` point to point	`pickupCityId`, `dropOffCityId`
`3` departure	`pickupCityId`, `dropOffAirportId`

Bookings

Endpoint	Required	Optional	Scope
POST `/bookings`	`holder.firstName`, `holder.lastName`, `items[].type`, `items[].rateToken`, `items[].guests[].firstName`, `items[].guests[].lastName`, `Idempotency-Key`	`clientReference`, `holder.email`, `holder.phone`, `note`, `specialRequests`, guest gender/type/age	`bookings:create`
GET `/bookings`	None	`clientReference`, `status`, `createdFrom`, `createdTo`, `checkInFrom`, `checkInTo`, `page`, `limit`	`bookings:read`
GET `/bookings/{bookingNumber}`	`bookingNumber`	None	`bookings:read`

{
  "clientReference": "AGENCY-123",
  "holder": {"firstName": "Ali", "lastName": "Valiyev", "email": "[email protected]"},
  "items": [
    {
      "type": "hotel",
      "rateToken": "rt_...",
      "guests": [
        {"firstName": "Ali", "lastName": "Valiyev"},
        {"firstName": "Leyla", "lastName": "Valiyeva"}
      ],
      "specialRequests": "High floor"
    }
  ]
}

If price changed, booking returns PRICE_CHANGED. If availability is not enough, booking returns INSUFFICIENT_AVAILABILITY or NOT_AVAILABLE. Request availability again and use the new rateToken.

Cancel

Endpoint	Required	Optional	Scope
POST `/bookings/{bookingNumber}/cancel-quote`	`bookingNumber`	`itemIds`	`bookings:cancel`
POST `/bookings/{bookingNumber}/cancel`	`bookingNumber`, `Idempotency-Key`	`itemIds`	`bookings:cancel`

cancel-quote calculates penalty only. cancel applies cancellation. Both use the original booking currency.

Modify

Endpoint	Required	Optional	Scope
POST `/bookings/{bookingNumber}/modify-quote`	`bookingNumber`, `itemId`, at least one change	`guests`, `specialRequests`, `bookingComment`, `customerComment`, `checkIn`, `checkOut`, `roomId`, `contractId`, `adults`, `childrenAges`, `currency`	`bookings:modify`
POST `/bookings/{bookingNumber}/modify`	`bookingNumber`, `itemId`, `confirm=true`, at least one change, `Idempotency-Key`	`guests`, `specialRequests`, `bookingComment`, `customerComment`, `checkIn`, `checkOut`, `roomId`, `contractId`, `adults`, `childrenAges`, `currency`	`bookings:modify`

Call modify-quote first, then send the same intended changes with confirm=true. Price-changing modify supports direct internal pending hotel items and direct TL2 API bookings when provider penalty is zero and only date/occupancy changes are requested. WTX-backed items, room/rate/property/nationality changes, paid items or commission-paid items return MODIFY_PRICE_CHANGE_NOT_SUPPORTED or MODIFY_REQUIRES_MANUAL_REVIEW. If date, room, occupancy, nationality or currency is changed, currency is required. If occupancy is changed, send the full guests list matching the new occupancy. PATCH /bookings/{bookingNumber} is kept as a compatibility alias.

{
  "itemId": 12345,
  "changes": {
    "checkIn": "2026-07-10",
    "checkOut": "2026-07-12",
    "adults": 2,
    "childrenAges": [],
    "currency": "USD",
    "guests": [
      {"firstName": "Ali", "lastName": "Valiyev", "type": "adult"},
      {"firstName": "Leyla", "lastName": "Valiyeva", "type": "adult"}
    ]
  }
}

Errors

Errors include a stable code, developer-readable message, optional field and hint.

{
  "success": false,
  "requestId": "req_20260617_120000_ab12cd34",
  "data": null,
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "message": "holder.firstName is required.",
      "field": "holder.firstName",
      "hint": ""
    }
  ]
}

Code	Meaning
`UNAUTHORIZED`, `KEY_REVOKED`	Missing, invalid or revoked API key.
`FORBIDDEN_SCOPE`	Key does not have the required scope.
`IP_NOT_ALLOWED`	Request IP is not allowed for the key.
`RATE_LIMITED`	Minute, hour or day request limit exceeded.
`VALIDATION_ERROR`	Request body, query or route parameter is invalid.
`IDEMPOTENCY_KEY_REUSED`	Same idempotency key was used for a different request.
`PRICE_CHANGED`	Selected rate price changed during booking revalidation.
`INSUFFICIENT_AVAILABILITY`, `NOT_AVAILABLE`	Selected product/rate is no longer available in the requested quantity.
`MODIFY_PRICE_CHANGE_NOT_SUPPORTED`, `MODIFY_REQUIRES_MANUAL_REVIEW`	Requested modification can not be safely completed automatically.
`EXTERNAL_API_ERROR`	Provider rejected or failed a synced API booking operation.
`INTERNAL_ERROR`	Unexpected server error. Send the `requestId` to BookingClub support.