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. Ages must be integers from 0 to 17; at most 10 children are accepted per room/item.
Request size	JSON request bodies are limited to 1 MiB.
Idempotency	Write endpoints require a 1-128 character visible ASCII `Idempotency-Key` without spaces. Retrying the exact same request with the same key returns the saved response without creating a duplicate booking. `POST /bookings` also blocks the same booking payload sent again too quickly with a different key.
Visibility	Products include supervisor internal contracts, enabled TL/TL2 products and WTX products visible to the supervisor.
Environment	Demo keys can read/change only demo orders. Live keys exclude demo orders and operate on normal/live orders for the same supervisor and client.
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.

Pagination is 1-based. Reference, tour, transfer and booking lists accept pages up to 1000.

Simulator

Requests are sent directly from this browser to https://api.bookingclub.net/v1. The key is kept only in this page's memory and is not saved. Production integrations must keep API keys server-side; never embed a live key in public browser or mobile-app code.

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	`name`, `propertyId`, `countryId`, `regionId`, `cityId`, `source`, `updatedSince`, `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. Property pages are limited to 100; use source, location, name, updatedSince, or an exact propertyId for targeted catalog discovery.

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-08-31",
  "checkOut": "2026-09-02",
  "currency": "USD",
  "nationalityId": 1,
  "rooms": [
    {"adults": 2, "childrenAges": []}
  ]
}

Tours

Endpoint	Required	Optional	Scope
GET `/tours`	None	`name`, `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`	`tours:read` + `availability:read`

Transfers

Endpoint	Required	Optional	Scope
GET `/transfers`	None	`name`, `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	`transfers:read` + `availability:read`

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

Hotel route fields use the numeric internal propertyId returned by GET /properties, not a user_accomodations.id row ID.

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	`bookingNumber`, `clientReference`, `status` integer `0`-`9`, `bookingDateFrom`, `bookingDateTo`, `firstCheckInFrom`, `firstCheckInTo`, `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"
    }
  ]
}

List filters match runtime names: use bookingDateFrom/bookingDateTo for booking creation date and firstCheckInFrom/firstCheckInTo for the first item check-in. status is an integer code from 0 to 9; text values such as pending are rejected.

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`, `confirm=true`, `cancelToken`, `Idempotency-Key`	`itemIds`	`bookings:cancel`

Call cancel-quote first, then send back the cancelToken it returns. cancel-quote calculates penalty only and returns a top-level cancelToken (opaque signed string, prefix rt_, ~15 min TTL). cancel applies cancellation and requires a JSON body containing {"confirm": true} plus the cancelToken from the quote. Both use the original booking currency. itemIds is optional; omit it or send an empty array to target all cancellable items.

A missing cancelToken returns VALIDATION_ERROR. The token binds the booking items and their quoted state. If a penalty or booking item changed, cancellation is rejected and a fresh quote is required. If provider cancellation fails, the local item is not marked cancelled. Multiple confirmed provider items must be quoted and cancelled one at a time with explicit itemIds.

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, `modifyToken` (price-affecting changes only), `Idempotency-Key`	`guests`, `specialRequests`, `bookingComment`, `customerComment`, `checkIn`, `checkOut`, `roomId`, `contractId`, `adults`, `childrenAges`, `currency`	`bookings:modify`
PATCH `/bookings/{bookingNumber}`	`bookingNumber`, `itemId`, `confirm=true`, at least one change, `modifyToken` (price-affecting changes only), `Idempotency-Key`	Same body as `POST /bookings/{bookingNumber}/modify`; compatibility alias for older clients.	`bookings:modify`

Call modify-quote first, then send back the same intended changes with confirm=true and the modifyToken it returned. For a price-affecting change, the token binds the exact requested changes, booking-item state and quoted price; it is only present for price-affecting quotes. modifyToken is required only for price-affecting changes. 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, paid or commission-paid items require manual review. If occupancy changes, send the full matching guests list. PATCH /bookings/{bookingNumber} remains a compatibility alias.

A missing modifyToken on a price-affecting modify returns VALIDATION_ERROR (field modifyToken). If the price changed since the quote, modify returns PRICE_CHANGED (field modifyToken) with details.quotedPrice and details.currentPrice; call modify-quote again for a fresh modifyToken. A price-affecting modify to a stay whose check-in is today or in the past returns NOT_MODIFIABLE.

{
  "itemId": 12345,
  "modifyToken": "rt_...",
  "changes": {
    "checkIn": "2026-08-31",
    "checkOut": "2026-09-02",
    "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`	Missing or invalid Authorization header.
`KEY_INVALID`	API key is invalid.
`KEY_DISABLED`	API key is disabled.
`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.
`RATE_LIMIT_UNAVAILABLE`	Rate-limit storage is temporarily unavailable; retry shortly.
`PAYLOAD_TOO_LARGE`	Request body exceeds the 1 MiB limit.
`VALIDATION_ERROR`	Request body, query or route parameter is invalid.
`NOT_FOUND`	Requested route or resource does not exist.
`METHOD_NOT_ALLOWED`	HTTP method is not allowed for this route.
`UNSUPPORTED_MEDIA_TYPE`	Request Content-Type is not supported; use application/json.
`INVALID_REFERENCE`	A referenced id such as a rate token or currency is invalid or expired.
`MISSING_PRICING_CONTEXT`	Required pricing context for the request is missing.
`IDEMPOTENCY_KEY_REUSED`	Same idempotency key was used for a different request.
`IDEMPOTENCY_IN_PROGRESS`	Same idempotency key is still being processed.
`DUPLICATE_BOOKING_REQUEST`	Same booking creation payload was sent again too quickly with a different idempotency key.
`PRICE_CHANGED`	Selected rate price changed during booking revalidation.
`BOOKING_CHANGED`	Booking item changed after quote/preparation; fetch it and quote again.
`PENALTY_UNAVAILABLE`	Provider penalty could not be verified, so cancellation was not attempted.
`ACCOUNTING_STATE_INVALID`	Required debt/accounting state is missing, so the money-changing operation was not attempted.
`INSUFFICIENT_AVAILABILITY`, `NOT_AVAILABLE`	Selected product/rate is no longer available in the requested quantity.
`NOT_CANCELLABLE`	Booking or item can not be cancelled through the API.
`CANCEL_ITEMS_INDIVIDUALLY`	Provider-backed items must be quoted/cancelled one at a time.
`NOT_MODIFIABLE`	Booking or item can not be modified through the API.
`MODIFY_NOT_SUPPORTED`	Modification is not supported for this booking or item type.
`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.