Hotel Supplier API (1.0)

Download OpenAPI specification: Download · Download Postman collection: Download

Tourmind hotel pull API for supplier

Integration Process

1. The supplier develops and tests the API.
2. The supplier provides the test environment URL, api key, and secret. Tourmind will create some test bookings.
3. The supplier completes the production environment configuration and provides the production environment URL, api key, and secret.
4. Tourmind creates a cancellable test booking in the production environment.
5. Go live

Authentication

All endpoints require an Authorization header using HMAC-SHA256 signature scheme.

Signature Generation Steps

1. Get the current Unix timestamp (integer seconds): timestamp
2. Concatenate the signature input: message = apiKey + apiSecret + timestamp
3. Compute HMAC-SHA256 of message using apiSecret as the key, then Base64-encode the result to get signature
4. Assemble the Authorization header: HMAC-SHA256 apikey={apiKey}, timestamp={timestamp}, signature={signature}

Example

Authorization: HMAC-SHA256 apikey=myApiKey, timestamp=1715000000, signature=Base64EncodedHmacSha256Result

Postman Script

const CryptoJS = require('crypto-js');

const apiKey = pm.environment.get("apiKey");
const apiSecret = pm.environment.get("secret");

if (!apiKey || !apiSecret) {
    console.error("Missing apiKey or secret");
    return;
}

const timestamp = Math.floor(Date.now() / 1000);

const message = apiKey + apiSecret + timestamp.toString();

const signature = CryptoJS.HmacSHA256(message, apiSecret).toString(CryptoJS.enc.Base64);

const authHeader = `HMAC-SHA256 apikey=${apiKey}, timestamp=${timestamp}, signature=${signature}`;

pm.request.headers.upsert({
    key: "Authorization",
    value: authHeader
});

Parameter Reference

Parameter	Description
apiKey	The API key is provided by the supplier
apiSecret	The API Secret is provided by the supplier
timestamp	Unix timestamp (seconds) at request time; server allows ±300 seconds tolerance
signature	Base64-encoded result of HMAC-SHA256(apiKey + apiSecret + timestamp, apiSecret)

Availability & Booking

Search

Search for bookable hotels and rooms that meet specific criteria. Note: When searching for multiple rooms, the same room type and rate plan apply to all rooms, but each room may have a different occupancy count. The returned price is the total amount (including taxes and fees, if applicable) for all rooms.

API Call Schema

Name	Value
Request URL	/search
Request method	POST

Request Fields

hotels[]: stringRequired

List of hotel codes to search. Maximum 30 hotels per request.

checkIn: stringRequired

Format: YYYY-MM-DD, e.g. 2025-08-15

checkOut: stringRequired

Format: YYYY-MM-DD. Must be after checkIn, e.g. 2025-08-16

roomId: integerRequired

Unique identifier for a room within the same request. Starts from 1 and increments.

adults: integerRequired

Number of adults occupying the room.

childrenAges[]: integer

Age of each child in the room. The array length determines the number of children.

language: string

Language for response content, e.g. en-US, zh-CN. Defaults to English if not provided.

currency: string

Desired price currency as ISO 4217 code, e.g. USD, CNY. Defaults to the supplier's base currency if not provided.

nationality: string

ISO 3166-1 alpha-2 country code, e.g. CN, US. Affects pricing and tax rates for some suppliers.

timeout: integer

Timeout in milliseconds.

requestId: stringRequired

A UUID generated by the caller for tracing and troubleshooting. Returned as-is in the response.

Response Fields

requestId: stringRequired

Matches the requestId sent in the request.

code: stringRequired

e.g. HOTEL_NOT_FOUND, PRICE_CHANGED.

message: stringRequired

Human-readable error description.

hotelCode: stringRequired

hotelName: stringRequired

code: stringRequired

Unique room type code within the supplier's system.

name: stringRequired

e.g. Deluxe Double Room

area: integer

Room area in square meters.

code: stringRequired

Supplier-defined bed type code, e.g. KING, DOUBLE, TWIN.

name: stringRequired

e.g. 1 King Bed

quantity: integerRequired

Number of this bed type in the room.

maxOccupancy: integer

Maximum total number of guests (adults + children) the room can accommodate.

maxAdults: integer

Maximum number of adults the room can accommodate.

maxChildren: integer

Maximum number of children the room can accommodate.

tourmind: string

expedia: string

agoda: string

juniper: stringRequired

travelgate: stringRequired

ctrip: stringRequired

meituan: stringRequired

token: string

Unique rate token from the supplier. Pass to Prebook Request.optionToken. Required by some suppliers.

ratePlanCode: stringRequired

Unique code for this rate within the supplier's system.

ratePlanName: stringRequired

e.g. Early Bird, Non-Refundable Rate

code: stringRequired

Standard meal plan code, e.g. RO (Room Only), BB (Bed & Breakfast), HB (Half Board), FB (Full Board), AI (All Inclusive).

name: stringRequired

e.g. Room Only, Bed & Breakfast

isIncludeChildren: booleanRequired

true means the meal plan covers children; false means adults only.

net: numberRequired

Total net price for all rooms and all nights

gross: numberRequired

Recommended retail price.

currency: stringRequired

ISO 4217 currency code, e.g. USD, CNY.

commission: number

type: stringRequired

Fee category code, e.g. RESORT_FEE, CITY_TAX, SERVICE_CHARGE.

name: stringRequired

Human-readable fee name, e.g. Resort Fee, City Tax.

amount: numberRequired

currency: stringRequired

ISO 4217 currency code.

included: booleanRequired

true means this fee is already included in Price.net; false means the guest must pay it separately at the hotel.

type: stringRequired

Fee category code, e.g. RESORT_FEE, CITY_TAX, SERVICE_CHARGE.

name: stringRequired

Human-readable fee name, e.g. Resort Fee, City Tax.

amount: numberRequired

currency: stringRequired

ISO 4217 currency code.

included: booleanRequired

true means this fee is already included in Price.net; false means the guest must pay it separately at the hotel.

refundable: booleanRequired

true indicates a cancellation before the deadline qualifies for a refund. See cancelPenalties for specific rules.

deadline: stringRequired

This penalty rule applies to cancellations made on or after this time. Format: ISO 8601, e.g. 2026-05-13T10:00:00Z.

penaltyType: stringRequired

NIGHTS: charged per night; PERCENT: charged as a percentage of the total price; AMOUNT: charged as a fixed amount.

value: numberRequired

Used together with penaltyType: number of nights for NIGHTS, percentage (e.g. 50 = 50%) for PERCENT, or monetary amount for AMOUNT.

currency: stringRequired

ISO 4217 currency code.

net: numberRequired

Net per night for all rooms

gross: numberRequired

Gross per night for all rooms

allotment: integer

allotment: integerRequired

Plan allotment available. Range: 1–99.

onRequest: boolean

true indicates the booking is not instantly confirmed and requires manual review by the supplier. Confirmation may be delayed. If the reservation cannot be confirmed within 60 seconds, set this to true.

remark: string

Additional supplier notes, such as special check-in conditions or promotional rules.

Body parameters

{
  "hotels": [
    "12345",
    "67891"
  ],
  "checkIn": "2026-08-15",
  "checkOut": "2026-08-16",
  "occupancies": [
    {
      "roomId": 1,
      "adults": 2,
      "childrenAges": [
        8
      ]
    },
    {
      "roomId": 2,
      "adults": 2,
      "childrenAges": [
        8
      ]
    }
  ],
  "currency": "USD",
  "nationality": "US",
  "timeout": 3000,
  "requestId": "16c74e57-9a86-4e17-843c-3dd66cf84788"
}

Responses

{
  "requestId": "16c74e57-9a86-4e17-843c-3dd66cf84788",
  "errors": null,
  "data": [
    {
      "hotelCode": "12345",
      "hotelName": "Hotel Name",
      "rooms": [
        {
          "roomType": {
            "code": "12345#DBL",
            "name": "Single room city view",
            "area": 25,
            "bedTypes": [
              {
                "code": "DBL",
                "name": "single bed",
                "quantity": 1
              }
            ],
            "maxOccupancy": 1,
            "maxAdults": 1,
            "maxChildren": 0,
            "relatedCode": {
              "Expedia": "1352345323",
              "HotelBed": "3432423423"
            }
          },
          "options": [
            {
              "token": "12345|12345#DBL#16#RF#32235",
              "ratePlanCode": "17",
              "ratePlanName": "Room Only",
              "mealPlan": {
                "code": "RO",
                "name": "Room Only",
                "isIncludeChildren": false
              },
              "price": {
                "net": 99.99,
                "gross": 99.99,
                "currency": "USD",
                "commission": 0
              },
              "fees": [
                {
                  "type": "TAX_AND_SERVICE_FEE",
                  "name": "tax and service fee",
                  "amount": 12.12,
                  "currency": "USD",
                  "included": false
                },
                {
                  "type": "EXTRA_PERSON_FEE",
                  "name": "Resort Fee",
                  "amount": 12.12,
                  "currency": "USD",
                  "included": true
                }
              ],
              "taxes": [
                {
                  "type": "CITY_TAX",
                  "name": "city tax",
                  "amount": 12.12,
                  "currency": "USD",
                  "included": false
                }
              ],
              "refundable": true,
              "cancelPenalties": [
                {
                  "deadline": "2026-04-17T16:58:48.131Z",
                  "penaltyType": "PERCENT",
                  "value": 100,
                  "currency": "USD"
                },
                {
                  "deadline": "2026-04-15T16:58:48.131Z",
                  "penaltyType": "AMOUNT",
                  "value": 20.2,
                  "currency": "USD"
                }
              ],
              "nightlyRate": {
                "2026-04-17": {
                  "net": 99.99,
                  "gross": 99.99,
                  "allotment": 9
                }
              },
              "allotment": 9,
              "onRequest": false,
              "remark": ""
            }
          ]
        }
      ]
    }
  ]
}

Prebook

Call this API before making a reservation. This operation will verify the real-time price and availability of the selected room type and return a bookingToken for use in subsequent booking requests. The bookingToken must be valid for at least 10 minutes. Timeout: 12s

API Call Schema

Name	Value
Request URL	/prebook
Request method	POST

Request Fields

requestId: stringRequired

A UUID generated by the caller for tracing.

hotelCode: stringRequired

checkIn: stringRequired

Format: YYYY-MM-DD

checkOut: stringRequired

Format: YYYY-MM-DD. Must be after checkIn.

roomId: integerRequired

Unique identifier for a room within the same request. Starts from 1 and increments.

adults: integerRequired

Number of adults occupying the room.

childrenAges[]: integer

Age of each child in the room. The array length determines the number of children.

roomCode: stringRequired

Room type code from the search results (SearchRoom.roomType.code).

ratePlanCode: stringRequired

Rate plan code from the search results (Option.ratePlanCode).

optionToken: string

The Option.token from the search results. Required by some suppliers to precisely identify the rate.

nationality: string

ISO 3166-1 alpha-2 country code, e.g. CN, US.

Response Fields

requestId: stringRequired

Matches the requestId sent in the request.

code: stringRequired

e.g. HOTEL_NOT_FOUND, PRICE_CHANGED.

message: stringRequired

Human-readable error description.

hotelCode: stringRequired

hotelName: stringRequired

roomCode: stringRequired

roomName: stringRequired

ratePlanCode: stringRequired

ratePlanName: string

bookingToken: stringRequired

Token used to create the booking. Pass to Booking Request.bookingToken. The token's validity period must be at least 10 minutes.

code: stringRequired

Standard meal plan code, e.g. RO (Room Only), BB (Bed & Breakfast), HB (Half Board), FB (Full Board), AI (All Inclusive).

name: stringRequired

e.g. Room Only, Bed & Breakfast

isIncludeChildren: booleanRequired

true means the meal plan covers children; false means adults only.

net: numberRequired

Total net price for all rooms and all nights

gross: numberRequired

Recommended retail price.

currency: stringRequired

ISO 4217 currency code, e.g. USD, CNY.

commission: number

type: stringRequired

Fee category code, e.g. RESORT_FEE, CITY_TAX, SERVICE_CHARGE.

name: stringRequired

Human-readable fee name, e.g. Resort Fee, City Tax.

amount: numberRequired

currency: stringRequired

ISO 4217 currency code.

included: booleanRequired

true means this fee is already included in Price.net; false means the guest must pay it separately at the hotel.

type: stringRequired

Fee category code, e.g. RESORT_FEE, CITY_TAX, SERVICE_CHARGE.

name: stringRequired

Human-readable fee name, e.g. Resort Fee, City Tax.

amount: numberRequired

currency: stringRequired

ISO 4217 currency code.

included: booleanRequired

true means this fee is already included in Price.net; false means the guest must pay it separately at the hotel.

net: numberRequired

Net per night for all rooms

gross: numberRequired

Gross per night for all rooms

allotment: integer

refundable: booleanRequired

deadline: stringRequired

This penalty rule applies to cancellations made on or after this time. Format: ISO 8601, e.g. 2026-05-13T10:00:00Z.

penaltyType: stringRequired

NIGHTS: charged per night; PERCENT: charged as a percentage of the total price; AMOUNT: charged as a fixed amount.

value: numberRequired

Used together with penaltyType: number of nights for NIGHTS, percentage (e.g. 50 = 50%) for PERCENT, or monetary amount for AMOUNT.

currency: stringRequired

ISO 4217 currency code.

allotment: integerRequired

onRequest: boolean

If the reservation cannot be confirmed within 60 seconds, set this to true.

remark: string

Body parameters

{
  "requestId": "16c74e57-9a86-4e17-843c-3dd6653453434",
  "hotelCode": "12345",
  "checkIn": "2026-03-23",
  "checkOut": "2026-03-24",
  "occupancies": [
    {
      "roomId": 1,
      "adults": 2,
      "childrenAges": null
    }
  ],
  "roomCode": "12345#DBL",
  "ratePlanCode": "1734534",
  "optionToken": "12345|12345#DBL#16#RF#32235",
  "nationality": "US"
}

Responses

{
  "requestId": "16c74e57-9a86-4e17-843c-3dd6653453434",
  "errors": null,
  "data": {
    "hotelCode": "12345",
    "hotelName": "hotel name",
    "roomCode": "12345#DBL",
    "roomName": "Single room city view",
    "ratePlanCode": "17",
    "ratePlanName": "Room Only",
    "bookingToken": "12345|12345#DBL#16#RF#32235|2026-03-23|2026-03-24|2",
    "mealPlan": {
      "code": "RO",
      "name": "Room Only",
      "isIncludeChildren": true
    },
    "price": {
      "net": 99.99,
      "gross": 99.99,
      "currency": "USD",
      "commission": 0
    },
    "fees": [
      {
        "type": "VALUE_ADDED_TAX",
        "name": "Resort Fee",
        "amount": 12.12,
        "currency": "USD",
        "included": false
      }
    ],
    "taxes": [
      {
        "type": "VALUE_ADDED_TAX",
        "name": "Resort Fee",
        "amount": 12.12,
        "currency": "USD",
        "included": true
      }
    ],
    "nightlyRate": {
      "2026-04-17": {
        "net": 99.99,
        "gross": 99.99,
        "allotment": 2
      }
    },
    "refundable": true,
    "cancelPenalties": [
      {
        "deadline": "2026-08-03T14:15:22.123Z",
        "penaltyType": "PERCENT",
        "value": 100,
        "currency": "USD"
      }
    ],
    "allotment": 2,
    "onRequest": true,
    "remark": ""
  }
}

Booking

The Booking operation requests a reservation confirmation for the specified rate option Timeout: 60s.

API Call Schema

Name	Value
Request URL	/booking
Request method	POST

Request Fields

requestId: stringRequired

A UUID generated by the caller for tracing and idempotency control.

referenceId: stringRequired

Tourmind Booking id

hotelCode: stringRequired

checkIn: stringRequired

Format: YYYY-MM-DD

checkOut: stringRequired

Format: YYYY-MM-DD

bookingToken: stringRequired

From Prebook Response.data.bookingToken.

firstName: stringRequired

lastName: stringRequired

phone: string

email: string

roomId: integerRequired

Corresponds to Occupancy.roomId in the search request.

firstName: stringRequired

lastName: stringRequired

age: integer

Required for children; optional for adults.

type: stringRequired

ADULT: adult; CHILD: children

totalPrice: numberRequired

From Prebook Response.data.price.net.

currency: stringRequired

Currency for totalPrice as an ISO 4217 code, e.g. USD, CNY.

nationality: string

ISO 3166-1 alpha-2 country code, e.g. CN, US.

customerRequirements: string

type: stringRequired

Currently supports virtual_card (virtual credit card).

number: stringRequired

Virtual credit card number.

securityCode: stringRequired

CVV/CVC security code.

expirationMonth: stringRequired

Two-digit month, e.g. 08.

expirationYear: stringRequired

Four-digit year, e.g. 2027.

givenName: stringRequired

familyName: stringRequired

countryCode: stringRequired

ISO 3166-1 alpha-2, e.g. US, CN.

postalCode: stringRequired

address: stringRequired

Response Fields

requestId: stringRequired

Matches the requestId sent in the request.

code: stringRequired

e.g. HOTEL_NOT_FOUND, PRICE_CHANGED.

message: stringRequired

Human-readable error description.

bookingCode: stringRequired

Booking number generated by the supplier's system. Used for subsequent queries and cancellations.

status: stringRequired

PENDING: processing; CONFIRMED: confirmed; FAILURE: booking failed; CANCELED: cancelled.

referenceId: stringRequired

Tourmind booking id

hotelConfirmationNumber: string

hotelCode: stringRequired

hotelName: string

checkIn: string

Format: YYYY-MM-DD

checkOut: string

Format: YYYY-MM-DD

firstName: stringRequired

lastName: stringRequired

phone: string

email: string

roomId: stringRequired

roomCode: stringRequired

roomName: string

ratePlanCode: string

ratePlanName: string

code: stringRequired

Standard meal plan code, e.g. RO (Room Only), BB (Bed & Breakfast), HB (Half Board), FB (Full Board), AI (All Inclusive).

name: stringRequired

e.g. Room Only, Bed & Breakfast

isIncludeChildren: booleanRequired

true means the meal plan covers children; false means adults only.

firstName: stringRequired

lastName: stringRequired

age: integer

Required for children; optional for adults.

type: stringRequired

ADULT: adult; CHILD: children

totalPrice: numberRequired

The actual settled net price (cost price).

penaltyAmount: number

Applicable for cancelled bookings. Represents the actual penalty amount incurred.

currency: stringRequired

Currency for totalPrice and penaltyAmount as an ISO 4217 code.

commission: number

Earnable commission amount for this booking.

deadline: stringRequired

This penalty rule applies to cancellations made on or after this time. Format: ISO 8601, e.g. 2026-05-13T10:00:00Z.

penaltyType: stringRequired

NIGHTS: charged per night; PERCENT: charged as a percentage of the total price; AMOUNT: charged as a fixed amount.

value: numberRequired

Used together with penaltyType: number of nights for NIGHTS, percentage (e.g. 50 = 50%) for PERCENT, or monetary amount for AMOUNT.

currency: stringRequired

ISO 4217 currency code.

remark: string

customerRequirements: string

bookedTime: string

Booking creation timestamp. Format: ISO 8601.

Body parameters

{
  "requestId": "16c74e57-9a86-4e34-843c-3dd66534ef434",
  "referenceId": "532432532",
  "hotelCode": "12345",
  "checkIn": "2026-08-24",
  "checkOut": "2026-08-25",
  "bookingToken": "12345|12345#DBL#16#RF#32235|2026-03-23|2026-03-24|2",
  "holder": {
    "firstName": "Shan",
    "lastName": "Zhang",
    "phone": "13212341234",
    "email": "xxx@xx.com"
  },
  "occupancies": [
    {
      "roomId": 1,
      "paxes": [
        {
          "firstName": "Shan",
          "lastName": "Zhang",
          "type": "ADULT"
        },
        {
          "age": 8,
          "type": "CHILD"
        }
      ]
    }
  ],
  "totalPrice": 99.99,
  "currency": "USD",
  "nationality": "US",
  "customerRequirements": "xxxxx"
}

Responses

{
  "requestId": "16c74e57-9a86-4e34-843c-3dd66534ef434",
  "errors": null,
  "data": {
    "bookingCode": "fef2fsf",
    "status": "CONFIRMED",
    "referenceId": "532432532",
    "hotelConfirmationNumber": "KHKHG324",
    "hotelCode": "12345",
    "hotelName": "hotel name",
    "checkIn": "2026-08-24",
    "checkOut": "2026-08-25",
    "holder": {
      "firstName": "Shan",
      "lastName": "Zhang",
      "phone": "13212341234",
      "email": "xxx@xx.com"
    },
    "rooms": [
      {
        "roomId": 1,
        "paxes": [
          {
            "firstName": "Shan",
            "lastName": "Zhang",
            "type": "ADULT"
          },
          {
            "age": 8,
            "type": "CHILD"
          }
        ]
      }
    ],
    "totalPrice": 99,
    "penaltyAmount": 0,
    "currency": "USD",
    "commission": 0,
    "cancelPenalties": [
      {
        "deadline": "2026-08-03T14:15:22.123Z",
        "penaltyType": "PERCENT",
        "value": 100,
        "currency": "USD"
      }
    ],
    "remark": "",
    "customerRequirements": "xxxxx",
    "bookedTime": "2026-08-20T14:15:22.123Z"
  }
}

Cancel

Cancel a confirmed reservation using the referenceId or bookingCode. Returns the cancellation status and the actual penalty amount incurred. Timeout: 60s.

API Call Schema

Name	Value
Request URL	/cancel
Request method	POST

Request Fields

requestId: stringRequired

A UUID generated by the caller for tracing and idempotency control.

referenceId: string

Tourmind booking id

bookingCode: string

Response Fields

requestId: stringRequired

code: stringRequired

e.g. HOTEL_NOT_FOUND, PRICE_CHANGED.

message: stringRequired

Human-readable error description.

referenceId: stringRequired

bookingCode: stringRequired

The booking number in the supplier's system.

status: stringRequired

Typically CANCELED after a successful cancellation.

penaltyAmount: numberRequired

The actual penalty amount incurred by this cancellation. 0 for free cancellations.

currency: stringRequired

Currency for penaltyAmount as an ISO 4217 code.

Body parameters

{
  "requestId": "16c74e57-9a86-4e17-843c-3dd66cf86524",
  "referenceId": "532432532"
}

Responses

{
  "requestId": "16c74e57-9a86-4e17-843c-3dd66cf86524",
  "errors": null,
  "data": {
    "referenceId": "532432532",
    "bookingCode": "fef2fsf",
    "status": "CANCELED",
    "penaltyAmount": 99.99,
    "currency": "USD"
  }
}

Booking List

Search for booking details using the following criteria:

1. referenceId: TourMind booking ID
2. bookingCode: Supplier booking ID
3. date range: Check-in / Booking Time Note: The supplier must support searching for bookings by referenceId or date range. When create or canceling a booking, network timeouts may prevent us from receiving a response; in such cases, we can only retrieve the booking status using the referenceId or date range. Timeout: 30s.

API Call Schema

Name	Value
Request URL	/bookings
Request method	POST

Request Fields

requestId: stringRequired

bookingCode: string

referenceId: string

dateType: string

Used with startDate/endDate. CHECKIN filters by check-in date; BOOK filters by booking creation date.

startDate: string

Format: YYYY-MM-DD. Used in combination with endDate and dateType.

endDate: string

Format: YYYY-MM-DD. Used in combination with startDate and dateType.

Response Fields

requestId: stringRequired

code: stringRequired

e.g. HOTEL_NOT_FOUND, PRICE_CHANGED.

message: stringRequired

Human-readable error description.

bookingCode: stringRequired

Booking number generated by the supplier's system. Used for subsequent queries and cancellations.

status: stringRequired

PENDING: processing; CONFIRMED: confirmed; FAILURE: booking failed; CANCELED: cancelled.

referenceId: stringRequired

Tourmind booking id

hotelConfirmationNumber: string

hotelCode: stringRequired

hotelName: string

checkIn: string

Format: YYYY-MM-DD

checkOut: string

Format: YYYY-MM-DD

firstName: stringRequired

lastName: stringRequired

phone: string

email: string

roomId: stringRequired

roomCode: stringRequired

roomName: string

ratePlanCode: string

ratePlanName: string

code: stringRequired

Standard meal plan code, e.g. RO (Room Only), BB (Bed & Breakfast), HB (Half Board), FB (Full Board), AI (All Inclusive).

name: stringRequired

e.g. Room Only, Bed & Breakfast

isIncludeChildren: booleanRequired

true means the meal plan covers children; false means adults only.

firstName: stringRequired

lastName: stringRequired

age: integer

Required for children; optional for adults.

type: stringRequired

ADULT: adult; CHILD: children

totalPrice: numberRequired

The actual settled net price (cost price).

penaltyAmount: number

Applicable for cancelled bookings. Represents the actual penalty amount incurred.

currency: stringRequired

Currency for totalPrice and penaltyAmount as an ISO 4217 code.

commission: number

Earnable commission amount for this booking.

deadline: stringRequired

This penalty rule applies to cancellations made on or after this time. Format: ISO 8601, e.g. 2026-05-13T10:00:00Z.

penaltyType: stringRequired

NIGHTS: charged per night; PERCENT: charged as a percentage of the total price; AMOUNT: charged as a fixed amount.

value: numberRequired

Used together with penaltyType: number of nights for NIGHTS, percentage (e.g. 50 = 50%) for PERCENT, or monetary amount for AMOUNT.

currency: stringRequired

ISO 4217 currency code.

remark: string

customerRequirements: string

bookedTime: string

Booking creation timestamp. Format: ISO 8601.

Body parameters

{
  "requestId": "16c74e57-9a86-4e34-843c-3dd66534ef434",
  "referenceId": "532432532"
}

Responses

{
  "requestId": "16c74e57-9a86-4e34-843c-3dd66534ef434",
  "errors": null,
  "data": [
    {
      "bookingCode": "fef2fsf",
      "status": "CONFIRMED",
      "referenceId": "532432532",
      "hotelConfirmationNumber": "KHKHG324",
      "hotelCode": "12345",
      "hotelName": "hotel name",
      "checkIn": "2026-08-24",
      "checkOut": "2026-08-25",
      "holder": {
        "firstName": "Shan",
        "lastName": "Zhang",
        "phone": "13212341234",
        "email": "xxx@xx.com"
      },
      "rooms": [
        {
          "roomId": 1,
          "paxes": [
            {
              "firstName": "Shan",
              "lastName": "Zhang",
              "type": "ADULT"
            },
            {
              "age": 8,
              "type": "CHILD"
            }
          ]
        }
      ],
      "totalPrice": 99,
      "penaltyAmount": 0,
      "currency": "USD",
      "commission": 0,
      "cancelPenalties": [
        {
          "deadline": "2026-08-03T14:15:22.123Z",
          "penaltyType": "PERCENT",
          "value": 100,
          "currency": "USD"
        }
      ],
      "remark": "",
      "customerRequirements": "xxxxx",
      "bookedTime": "2026-08-20T14:15:22.123Z"
    }
  ]
}

Static Data

Hotel List

Retrieve hotel static data including basic hotel information and room type lists. Supports filtering by hotel code, country, or last update time. Results are paginated.

API Call Schema

Name	Value
Request URL	/hotels
Request method	POST

Request Fields

hotels[]: string

Specific hotel codes to query. Maximum 100. Mutually exclusive with countryCode. If neither is provided, all hotels are returned (paginated).

countryCode: string

ISO 3166-1 alpha-2 country code to filter hotels by country, e.g. CN, JP.

updateTime: string

Returns only hotels that have changed since this timestamp. Used for incremental static data sync. Format: ISO 8601.

page: integer

Starts from 1.

perPage: integer

Number of hotels per page. Range: 1–100. Defaults to 100.

Response Fields

code: stringRequired

e.g. HOTEL_NOT_FOUND, PRICE_CHANGED.

message: stringRequired

Human-readable error description.

page: integerRequired

perPage: integerRequired

pages: integerRequired

Total number of pages.

total: integerRequired

Total number of hotels matching the criteria.

hotelCode: stringRequired

Unique hotel code within the supplier's system.

hotelName: stringRequired

starRating: integerRequired

Hotel star classification. Range: 1–5.

category: string

e.g. Hotel, Resort, Hostel, Apartment.

countryCode: stringRequired

ISO 3166-1 alpha-2, e.g. CN, JP, US.

country: stringRequired

cityCode: string

Supplier-defined city code.

city: string

address: stringRequired

latitude: stringRequired

WGS84 latitude, e.g. 39.9042.

longitude: stringRequired

WGS84 longitude, e.g. 116.4074.

email: string

phone: string

Include international dialing code, e.g. +8610-12345678.

code: stringRequired

Unique room type code within the supplier's system.

name: stringRequired

e.g. Deluxe Double Room

area: integer

Room area in square meters.

code: stringRequired

Supplier-defined bed type code, e.g. KING, DOUBLE, TWIN.

name: stringRequired

e.g. 1 King Bed

quantity: integerRequired

Number of this bed type in the room.

maxOccupancy: integer

Maximum total number of guests (adults + children) the room can accommodate.

maxAdults: integer

Maximum number of adults the room can accommodate.

maxChildren: integer

Maximum number of children the room can accommodate.

tourmind: string

expedia: string

agoda: string

juniper: stringRequired

travelgate: stringRequired

ctrip: stringRequired

meituan: stringRequired

tourmind: string

expedia: string

agoda: string

juniper: stringRequired

travelgate: stringRequired

ctrip: stringRequired

meituan: stringRequired

Body parameters

{
  "hotels": [
    "12345"
  ],
  "page": 1,
  "perPage": 100
}

Responses

{
  "errors": null,
  "data": {
    "pagination": {
      "page": 1,
      "perPage": 100,
      "pages": 1,
      "total": 1
    },
    "hotels": [
      {
        "hotelCode": "12345",
        "hotelName": "hotel name",
        "starRating": 3,
        "category": "Hotel",
        "countryCode": "US",
        "country": "USA",
        "cityCode": "CA",
        "city": "Burlingame",
        "address": "600 Airport Boulevard",
        "latitude": "37.59002",
        "longitude": "-122.342915",
        "email": "",
        "phone": "1-650-340-8500",
        "relatedCode": {
          "expedia": "1232353"
        },
        "rooms": [
          {
            "code": "DBL",
            "name": "Double Room",
            "area": 20,
            "bedTypes": [
              {
                "code": "2",
                "name": "Single Bed",
                "quantity": 2
              }
            ],
            "maxOccupancy": 2,
            "maxAdults": 2,
            "maxChildren": 0,
            "relatedCode": {
              "expedia": "3253252"
            }
          }
        ]
      }
    ]
  }
}

Reference

Booking Status

Value	Description
PENDING	Booking is being processed; confirmation is pending.
CONFIRMED	Booking has been confirmed by the supplier.
FAILURE	Booking failed to be confirmed.
CANCELED	Booking has been cancelled.

Meal Plan Codes

Code	Description
RO	Room Only
BB	Bed & Breakfast
HB	Half Board (Breakfast + Dinner)
FB	Full Board (Breakfast + Lunch + Dinner)
AI	All Inclusive
BF1	Breakfast for 1 person
BF2	Breakfast for 2 persons
BF3	Breakfast for 3 persons
BF4	Breakfast for 4 persons
LC	Lunch
DN	Dinner
LD	Lunch & Dinner

Fee / Tax Types

Value	Description
VALUE_ADDED_TAX	Value Added Tax (VAT)
SALES_TAX	Sales Tax
CITY_TAX	City Tax
TOURISM_TAX	Tourism Tax
TAX_AND_SERVICE_FEE	Combined Tax & Service Fee
PROPERTY_FEE	Property Fee
DEPOSIT	Security Deposit
RESORT_FEE	Resort Fee
EXTRA_PERSON_FEE	Extra Person Fee
PLATFORM_FEE	Platform Fee

Date Type

Value	Description
CHECKIN	Filter bookings by check-in date.
BOOK	Filter bookings by booking creation date.

Guest Type

Value	Description
ADULT	Adult (18 years or older).
CHILD	Child (17 years or younger).

Error Codes

Code	Description
VALIDATION_ERROR	Request parameter validation failed.
TIMEOUT	The upstream supplier request timed out.
RATE_LIMIT	Request rate limit exceeded.
SYSTEM_ERROR	Internal system error.
NO_AVAILABILITY	No availability for the requested criteria.
PRICE_CHANGED	The price has changed since the last search or prebook.
INSUFFICIENT_CREDIT	Account credit is insufficient to complete the booking.
UNKNOWN	An unknown error occurred.