Business Travel Suite Knowledge Base

TABLE OF CONTENTS

Request Example
Request Specification
Response Example

BTS Multi-hotel Availability Shopping is a fast shopping API for distributors to query availability of multiple hotels from ARI cache or supplier CRS. It provides high performance, high accuracy and high TPS.

POST 
URL: {endpoint}//shopping/multihotels

Request Example

{
  "header": {
    "distributorId": "string",
    "version": "v1",
    "token": "be5b09acd91b45988f3f9dff595563f0"
  },
  "hotels": [
    {
      "supplierId": "HILTON",
      "hotelId": "GATHI"
    }
  ],
  "corpCode": "string",
  "stayRange": {
    "checkin": "2024-01-01",
    "checkout": "2024-01-04"
  },
  "roomCriteria": {
    "roomCount": 2,
    "adultCount": 1,
    "childCount": 2,
    "childAges": [
      4,
      8
    ]
  },
  "iata": "string",
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}

Request Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@supplierId	string	Yes	MaxLength: 32 The ID of the hotel supplier in DerbySoft's system	HILTON
@distributorId	string	Yes	MaxLength: 32 The ID of the distributor in DerbySoft's system	MOCK_DISTRIBUTOR
@version	string	Yes	MaxLength: 20 Version of API	v1.0.0
@token	string	Yes	MaxLength: 64 A unique ID to identify request and response, normally it should be UUID.	18393849028490234
hotelId	string	Yes	Hotel ID in supplier's system	GATHI
stayRange	object	Yes	/	/
@checkin	string	Yes	Check-in, format with yyyy-MM-dd	2024-01-01
@checkout	string	Yes	Check out, format with yyyy-MM-dd	2024-01-04
roomCriteria	object	Yes	/	/
@roomCount	integer	Yes	Total room count per request	2
@adultCount	integer	Yes	Adult count per room	1
@childCount	integer	No	Child count per room	2
@childAges	array	No	Child ages for each child, array size MUST be the same as a child count.	[ 4, 8 ]
corpCode	string	No	Corp ID in distributor’s system	DIS
iata	string	No	IATA of distributor	/
extensions	object	No	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field. For more information refer to: Sensitive Information	/

Response Example

Success Response (HTTP Status 200)

{
  "header": {
    "distributorId": "string",
    "version": "v1",
    "token": "be5b09acd91b45988f3f9dff595563f0"
  },
  "stayRange": {
    "checkin": "2024-01-01",
    "checkout": "2024-01-04"
  },
  "iata": "string",
  "availHotels": [
    {
      "supplierId": "HILTON",
      "hotelId": "GATHI",
      "availRoomRates": [
        {
          "roomCriteria": {
            "roomCount": 2,
            "adultCount": 1,
            "childCount": 2,
            "childAges": [
              4,
              8
            ]
          },
          "inventory": 2,
          "roomId": "K1D",
          "rateId": "ODAD01",
          "rateFlag": "Corporate",
          "currency": "USD",
          "amountBeforeTax": [
            100,
            100,
            120
          ],
          "amountAfterTax": [
            110,
            110,
            130
          ],
          "mealPlan": "RO",
          "paymentType": "PayNow",
          "guarantee": {
            "guaranteeType": "CCG"
          },
          "fees": [
            {
              "dateRange": {
                "startDate": "2024-01-01",
                "endDate": "2024-01-04"
              },
              "fee": {
                "name": "Service Charge",
                "type": "Exclusive",
                "amount": 10,
                "amountType": "Percent",
                "chargeType": "PerRoomPerNight",
                "paymentType": "PayNow",
                "effectivePerson": 0
              }
            }
          ],
          "cancelPolicy": {
            "code": "AD100P_100P",
            "description": "Non Refundable",
            "cancelPenalties": [
              {
                "noShow": true,
                "cancellable": true,
                "cancelDeadline": {
                  "offsetTimeDropType": "BeforeArrival",
                  "offsetTimeUnit": "D",
                  "offsetTimeValue": 999,
                  "deadline": "string"
                },
                "penaltyCharge": {
                  "chargeBase": "FullStay",
                  "nights": 0,
                  "amount": 0,
                  "percent": 0
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Error Response(HTTP Status 401)

{
  "errorCode": "string",
  "supplierErrorCode": "string",
  "errorMessage": "string"
}

Error Response(HTTP Status 500)

{
  "errorCode": "string",
  "supplierErrorCode": "string",
  "errorMessage": "string"
}

Response Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@supplierId	string	Yes	MaxLength: 32 The ID of the hotel supplier in DerbySoft's system	HILTON
@distributorId	string	Yes	MaxLength: 32 The ID of the distributor in DerbySoft's system	MOCK_DISTRIBUTOR
@version	string	Yes	MaxLength: 20 Version of API	v1.0.0
@token	string	Yes	MaxLength: 64 A unique ID to identify request and response, normally it should be UUID.	18393849028490234
hotelId	string	Yes	Hotel ID in supplier's system	GATHI
stayRange	object	Yes	/	/
@checkin	string	Yes	Check-in, format with yyyy-MM-dd	2024-01-01
@checkout	string	Yes	Check out, format with yyyy-MM-dd	2024-01-04
roomCriteria	object	Yes	/	/
@roomCount	integer	Yes	Total room count per request	2
@adultCount	integer	Yes	Adult count per room	1
@childCount	integer	No	Child count per room	2
@childAges	array	No	Child ages for each child, array size MUST be the same as the child count/	[ 4, 8 ]
iata	string	No	IATA of distributor	/
roomRates		Yes	Meal plan, fee, and cancel policy are optional fields as some distributors do not support these in the API.	/
@inventory	integer	Yes	Available inventory count according to request criteria	1
@promoteCode	string	No	the code for the promotion applied to this rate, It's required when isAfterPromotion = true.	discount001
@roomId	string	Yes	Room ID in supplier system	10000101
@rateId	string	Yes	Rate ID in supplier system	123456
@currency	string	Yes	Currency code [ISO-4217]	USD
@amountBeforeTax	array[number]	No	The daily amount of rate without tax & fee	[ 100, 100, 120 ]
@amountAfterTax	array[number]	No	The daily amount of rate with tax & fee	[ 110, 110, 130 ]
@mealPlan	string	No	meal plan code list.	RO
@paymentType	enum	No	Indicates the product is prepaid to the hotel (PayNow) or pay at the hotel (PayLater) Enum: [ PayLater, PayNow ]	PayNow
roomRates / guarantee	object	No	Guarantee information for this room rate.	/
@guaranteeType	string	Yes	guarantee type list.	CCG
roomRates.fees	array[object]	No	Fee or tax by date range.	/
fees.dateRange	object	Yes	/	/
@startDate	string	Yes	Start date of date range, format with yyyy-MM-dd	2024-01-01
@endDate	string	Yes	End date of date range, format with yyyy-MM-dd	2024-01-04
fees.fee		Yes	/	/
@name	string	Yes	Pattern: \w[\w\d]+	Service Charge
@type	enum	Yes	The fee or tax is included in the amount before tax or not. Enum: [ Inclusive, Exclusive ]	Exclusive
@amount	number	Yes	Amount value of fee or tax	10
@amountType	string	Yes	Indicates how to charge the tax, 10% per room per night in this example Enum: [ Fix, Percent ]	Percent
@chargeType	string	Yes	Enum: [ PerRoomPerNight, PerPersonPerNight, PerRoomPerStay, PerPersonPerStay ]	PerRoomPerNight
@paymentType	enum	No	Indicates the fee is prepaid to the hotel (PayNow) or pay at the hotel (PayLater) Enum: [ PayLater, PayNow ]	PayNow
@effectivePerson	number	No	This means the fee that will be charged based on how many persons, like extra person charge, usually applied from 3, so the 1 adult, 2 adults will be same, 3 adults will be charged an extra fee.	/
roomRates.cancelPolicy	object	No	Cancellation Policy"	/
@code	string	Yes	Max Length: 128 Code of cancel policy	AD100P_100P
@description	string	No	Max Length: 1024 cancel policy	Non Refundable
cancelPolicy. cancelPenalties		Yes	Detail about the cancel Penalty	/
@noShow	boolean	Yes	If true, it means the penaltyCharge applied for No-Show, and the cancellable, cancelDeadline will NOT exist.	/
@cancellable	boolean	No	Indicates cancel is allowed or not. If false, it cannot be canceled. If true, the cancelDeadline will exist.	/
cancelPenalties. cancelDeadline		No	/	/
@offsetTimeDropType	enum	No	Enum: [ BeforeArrival ] An enumerated type indicates when the deadline drop time goes into effect.	/
@offsetTimeUnit	enum	No	Enum: [ D, H ]	/
@offsetTimeValue	number	No	The number of offset times with the time unit.	/
@deadline	string	No	local deadline time allowed for cancellation, like 4 PM, or 6 PM.	/
cancelPenalties. penaltyCharge	/	/	/	/
@chargeBase	enum	No	Enum: [ FullStay, NightBase ] if FullStay, it will be a percentage or amount, if NightBase, the nights are required.	/
@nights	number	No	Exists if the penalty charge is based on the night, like the first night.	/
@amount	number	No	Exists if the penalty charge is a flat charge, like USD 30.00.	/
@percent	number	No	Exists if the penalty charge is percent, like 15.5 means 15.5%.	/
extensions	object	No	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field. For more information refer to: Sensitive Information	/

Multi-hotel Avail Shopping API

Request Example

Request Specification

Response Example

Response Specification