Distributor Knowledge Base

TABLE OF CONTENTS

Live check API

Live Check API

The Live Check API allows distributors to query real-time availability from hotel suppliers or Derbysoft cache, ensuring they receive up-to-date information on all available rooms and rates. This functionality is essential for ensuring that the data presented to customers reflects the current status of hotel inventory. If a hotel supplier does not support the live check function, the check will be done in the DerbySoft cache to provide availability data. Additionally, the Live Check API supports a maximum stay of up to 61 days, depending on the supplier’s capabilities. This flexibility enables distributors to check long-term availability and offer extended stay options to their customers, provided the supplier supports this duration.

The implementation of this API is a mandatory step in the booking flow, ensuring accurate and timely availability information before proceeding with further reservation actions.

POST /availability HTTP/1.1
URL: {BookingUSB-Endpoint}/availability
Authorization: 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Live Check Request Schema

Request(METHOD: POST)
Level	Field Name	Data Type	Required	Description	Example
1	header	object	Y	/	/
2	@supplierId	string	Y	The ID of the hotel supplier in DerbySoft's system MaxLength: 32	HILTON
2	@distributorId	string	Y	The ID of the distributor in DerbySoft's system MaxLength: 32	GTA
2	@version	string	Y	Version of API MaxLength: 20	v4
2	@token	string	Y	A unique identifier is used for requests and responses, typically a UUID. MaxLength: 64 Note that this is an echo token, not an access token.	18393849028490234
1	hotelId	string	Y	Hotel IDs provided by hotel suppliers contain the following characters only: 1. Digits (0-9) 2. Uppercase letters (A-Z) 3. Hyphen ('-')	100001 GATHI 00016 PEP-B3T2 B8W7
1	stayRange	object	Y	/	/
2	@checkin	string	Y	Check in date expressed YYYY-MM-DD	2028-01-01
2	@checkout	string	Y	Check out date expressed YYYY-MM-DD	2028-01-04
1	roomCriteria	object	Y	/	/
2	@roomCount	integer	Y	Total room count per request	2
2	@adultCount	integer	Y	Adult count per room	1
2	@childCount	integer	N	Child count per room	2
2	@childAges	array	N	Child ages for each child, array size MUST be the same as a child count.	[ 4, 8 ]
1	productCandidate	object	N	/	/
2	@roomId	string	N	Room ID in supplier's system	K1D
2	@rateId	string	N	Rate ID in supplier's system	ODAD01
1	iata	string	N	IATA of distributor	/
1	loyaltyAccount	object	N	/	/
2	@programCode	string	C	Loyalty program code of the supplier	BW
2	@accountId	string	C	Loyalty program ID of the guest	123456
1	corpAccount	object	N	Please note that the current feature will be deprecated. Instead, please implement the 'corpCodes' node.	/
2	@corpProgramCode	string	C	Corporate Hotel Program of a hotel supplier	CR
2	@corpId	string	C	Corporate ID in the program account	A-1232
1	isAfterPromotion	boolean	N	The flag indicates calculating the available room rates with the promotion rules or not. TRUE means checking the availability under the promotion rules provided by the supplier. FALSE means you do not need to check the availability under any promotions, basic live-check only.	false
1	promoteCode	string	N	Promote code defined by the hotel, is an optional field when you want to request the promotion rates (isAfterPromotion=true). If promote code is empty and there are multiple promotions available for one product at the same time, the promotion rule will be chosen according to multiPromotionsStategy.	/
1	bookingChannel	string	N	Sub-distributor ID	/
1	extensions	object	N	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	/
1	onlyExactMatch	boolean	N	Only return the rate plans that are allocated to the corpCode and do not return any other public rate plans. Note: If the corpCodes are not specified, the field will be ignored.	false
1	corpCodes	array[string]	N	Notes: 1. It depends on the corporate code mapping between Go Distributors and hotel suppliers. If the mapping is not in place and corporate codes are passed, an error will occur. 2. The maximum number of corpCodes allowed is 10.	["CORPA", "CORPB"]

Live Check Request Example

Live Check Request Example

{
    "header": {
      "supplierId": "HILTON",
      "distributorId": "GTA",
      "version": "v4",
      "token": "18393849028490234"
    },
    "hotelId": "GATHI",
    "stayRange": {
      "checkin": "2028-01-01",
      "checkout": "2028-01-04"
    },
    "roomCriteria": {
      "roomCount": 2,
      "adultCount": 1,
      "childCount": 2,
      "childAges": [
        4,
        8
      ]
    },
    "productCandidate": {
      "roomId": "K1D",
      "rateId": "ODAD01"
    },
    "iata": "string",
    "loyaltyAccount": {
      "programCode": "BW",
      "accountId": "1234567890123457"
    },
    "corpAccount": {
      "corpProgramCode": "CR",
      "corpId": "A-1232"
    },
    "isAfterPromotion": false,
    "promoteCode": "string",
    "bookingChannel": "string",
    "extensions": {
      "sendProductInformation": "true",
      "key2": "value2"
    },
    "onlyExactMatch": false,
    "corpCodes": [
      "CORPA",
      "CORPB"
    ]
  }

Live Check Response Schema

Response
Level	Field Name	Data Type	Required	Description	Example
1	header	object	Y	/	/
2	@supplierId	string	Y	The ID of the hotel supplier in DerbySoft's system MaxLength: 32	HILTON
2	@distributorId	string	Y	The ID of the distributor in DerbySoft's system MaxLength: 32	GTA
2	@version	string	Y	Version of API MaxLength: 20	v4
2	@token	string	Y	A unique identifier is used for requests and responses, typically a UUID. Note that this is an echo token, not an access token. MaxLength: 64	18393849028490234
1	hotelId	string	Y	Hotel IDs provided by hotel suppliers contain the following characters only: 1. Digits (0-9) 2. Uppercase letters (A-Z) 3. Hyphen ('-')	100001 GATHI 00016 PEP-B3T2 B8W7
1	stayRange	object	Y	/	/
2	@checkin	string	Y	Check in date expressed YYYY-MM-DD	2028-01-01
2	@checkout	string	Y	Check out date expressed YYYY-MM-DD	2028-01-04
1	roomCriteria	object	Y	/	/
2	@roomCount	integer	Y	Total room count per request	2
2	@adultCount	integer	Y	Adult count per room	1
2	@childCount	integer	N	Child count per room	2
2	@childAges	array	N	Child ages for each child, array size MUST be the same as the child count/	[ 4, 8 ]
1	productCandidate	object	N	/	/
2	@roomId	string	N	Room ID in supplier system	K1D
2	@rateId	string	N	Rate ID in supplier system	ODAD01
1	iata	string	N	IATA of distributor	/
1	roomRates		Y	Meal plan, fee, and cancellation policy are optional fields as some distributors do not support these in the API.	/
2	@inventory	integer	Y	Available inventory count according to the request criteria	1
2	@isAfterPromotion	boolean	N	The flag indicates calculating the available room rates with the promotion rules or not. Default is false if null TRUE means to check the availability that is under the promotion rules provided by the supplier. FALSE means you do not need to check the availability under any promotions, basic live-check only.	false
2	@promoteCode	string	N	The code for the promotion applied to this rate. It's required when isAfterPromotion = true.	discount001
2	@roomId	string	Y	Room ID in supplier system	10000101
2	@roomName	string	N	Max length: 256	King Room
2	@roomDescription	string	N	/	Soak in city views in our Deluxe room, which features a well-appointed ensuite bathroom and up-to-date entertainment offerings.
2	@rateId	string	Y	Rate ID in supplier system	BAR
2	@rateName	string	N	Max length: 256	Best Available Rate
2	@rateDescription	string	N	/	Begin your day with a hearty meal
2	@connectionType	enum	N	Enum: [Exchange, Standard] Indicates the connection type of products. Notes: If the field is omitted, it means the Connection Type is Standard.	Exchange
2	corpCodes	array[string]	N	Corporate ID for a specific company, consortia, negotiated rate used to retrieve rates related to that code	["CORPA", "CORPB"]
2	isLoyaltyEligible	boolean	N	Used to indicate if a specific rate is eligible for loyalty. true: means that the rate is eligible. false: indicates the rate is not eligible for loyalty	false
2	commission	object	N	Object used to indicate if a specific rate is commissionable.	/
3	@value	number	C	value of the commission	10
3	@type	enum	C	Enum: [Percent, Amount] Commission type	Percent
2	@currency	string	Y	Currency code [ISO-4217]	USD
2	@amountBeforeTax	array[number]	N	The daily rate for a single room, excluding taxes and fees.	[ 100, 100, 120 ]
2	@amountAfterTax	array[number]	N	The daily rate for a single room, including taxes and fees.	[ 110, 110, 130 ]
2	suggestedTotalPrice	object	N	Notes: If the connection type is "Exchange" and "Net" Rate Model, the node will be visible; otherwise, it will not appear.	/
3	@amountBeforeTax	number	N	/	600
3	@amountAfterTax	number	N	/	700
2	@mealPlan	string	N	Meal plan code: refer to the standard meal plan code list.	RO
2	@paymentType	enum	N	Enum: [ PayLater, PayNow ] Indicates the product is prepaid to the hotel (PayNow) or pay at the hotel (PayLater).	PayNow
2	guarantee	object	N	Guarantee information for this room rate.	/
3	@guaranteeType	string	C	The type of guarantee method. Refer to the standard guarantee type list.	CCG
2	fees	array[object]	N	Fee or tax by date range.	/
3	dateRange	object	Y	/	/
4	@startDate	string	Y	Start date expressed YYYY-MM-DD	2028-01-01
4	@endDate	string	Y	End date expressed YYYY-MM-DD	2028-01-04
3	fee	object	Y	/	/
4	@name	string	Y	pattern: \w[\w\d]+ { starts with a word character (letter, number, or underscore) followed by one or more word characters or digits.}	Service Charge
4	@type	enum	Y	Enum: [ Inclusive, Exclusive ] The fee or tax is included in the amount before tax or not.	Exclusive
4	@amount	number	Y	Amount value of fee or tax	10
4	@amountType	string	Y	Enum: [ Fix, Percent ] Indicates how to charge the tax, 10% per room per night in this example.	Percent
4	@chargeType	string	Y	Enum: [ PerRoomPerNight, PerPersonPerNight, PerRoomPerStay, PerPersonPerStay ] Indicates how the fee is charge[PerRoomPerNight, PerPersonPerNight, PerRoomPerStay, PerPersonPerStay]	PerRoomPerNight
4	@paymentType	enum	N	Enum: [ PayLater, PayNow ] Indicates if the fee is prepaid to hotels(PayNow) or paid at the hotel(PayLater). Note: The 'paymentType' field will be replaced by 'collectBy' and removed from the API in the future.	PayNow
4	@collectBy	enum	N	Enum: [Distributor, Property] Indicates that the fee (e.g., City Tax, Tourist Tax) should be collected by the hotel(Property) at check-in or by distributors when guests make a reservation(Distributor).	Distributor
4	@effectivePerson	number	N	It indicates the fee will be charged starting from which occupancy, such as the "Extra Person Charge" fee. The EffectivePerson is 3, meaning an extra fee will be applied from the third person onward.	3
2	cancelPolicy	object	N	Cancellation policy defines what penalty will be charged when a guest cancels the booking at a certain advance time range. The penalty is related to No-show or a time range before No-show.	/
3	@code	string	C	Code of cancel policy Max Length: 128	AD100P_100P
3	@description	string	N	Description of the cancel policy Max Length: 1024	Non Refundable
3	cancelPenalties	array[object]	C	Details about the cancel Penalty	/
4	@noShow	boolean	C	If true, it means the penaltyCharge applied for No-Show, and the cancellable, cancelDeadline will NOT exist.	/
4	@cancellable	boolean	N	Indicates whether cancel is allowed or not. If false, it cannot be canceled. If true, the cancelDeadline will exist.	/
4	cancelDeadline		N	/	/
5	@offsetTimeDropType	enum	N	Enum: [ BeforeArrival ] An enumerated type indicates when the deadline drop time goes into effect.	/
5	@offsetTimeUnit	enum	N	Enum: [ D, H ]	/
5	@offsetTimeValue	number	N	The number of offset times with the time unit.	/
5	@deadline	string	N	local deadline time allowed for cancellation, like 4 PM or 6 PM.	/
4	penaltyCharge	/	/	/	/
5	@chargeBase	enum	N	Enum: [ FullStay, NightBase ] If FullStay, it will be a percentage or an amount. f NightBase, the nights are required.	/
5	@nights	number	N	Exists if the penalty charge is based on the night, like the first night.	/
5	@amount	number	N	Exists if the penalty charge is a flat charge, like USD 30.00.	/
5	@percent	number	N	Exists if the penalty charge is a percent, like 15.5 means 15.5%.	/
1	extensions	object	N	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	/
1	error	string	N	error response	Key not authorized
1	errorCode	string	C	error response	InvalidField
1	supplierErrorCode	string	C	error response	InvalidField
1	errorMessage	string	C	error response	Invalid Message

Live Check Response Example

Success Response (HTTP Status 200)

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotelId": "GATHI",
  "stayRange": {
    "checkin": "2028-01-01",
    "checkout": "2028-01-04"
  },
  "roomCriteria": {
    "roomCount": 2,
    "adultCount": 1,
    "childCount": 2,
    "childAges": [
      4,
      8
    ]
  },
  "productCandidate": {
    "roomId": "K1D",
    "rateId": "ODAD01"
  },
  "iata": "string",
  "roomRates": [
    {
      "inventory": 2,
      "isAfterPromotion": true,
      "promoteCode": "discount001",
      "roomId": "K1D",
      "roomName": "Double Room",
      "roomDescription": "Soak in city views in our Deluxe room, which features a well-appointed ensuite bathroom and up-to-date entertainment offerings.",
      "rateId": "ODAD01",
      "rateName": "Standard Rate",
      "rateDescription": "Standard Rate Includes Breakfast",
      "connectionType": "Standard",
      "corpCodes": [
          "CORPA",
          "CORPB"
        ],
      "isLoyaltyEligible": true,
      "commission": {
        "value": 10,
        "type": "Percent"
      },
      "currency": "USD",
      "amountBeforeTax": [
        100,
        100,
        120
      ],
      "amountAfterTax": [
        110,
        110,
        130
      ],
      "mealPlan": "RO",
      "paymentType": "PayNow",
      "guarantee": {
        "guaranteeType": "CCG"
      },
      "fees": [
        {
          "dateRange": {
            "startDate": "2028-01-01",
            "endDate": "2028-01-04"
          },
          "fee": {
            "name": "Service Charge",
            "type": "Exclusive",
            "amount": 10,
            "amountType": "Percent",
            "chargeType": "PerRoomPerNight",
            "paymentType": "PayNow",
            "collectBy": "Distributor",
            "effectivePerson": 0
          }
        },
        {
          "dateRange": {
            "startDate": "2028-01-01",
            "endDate": "2028-01-04"
          },
          "fee": {
            "name": "City Tax",
            "type": "Exclusive",
            "amount": 5,
            "amountType": "Fix",
            "chargeType": "PerPersonPerNight",
            "paymentType": "PayLater",
            "collectBy": "Property",
            "effectivePerson": 0
          }
        }
      ],
      "cancelPolicy": {
        "code": "AD100P_100P",
        "description": "Non Refundable",
        "cancelPenalties": [
          {
            "noShow": true,
            "cancellable": true,
            "cancelDeadline": {
              "offsetTimeDropType": "BeforeArrival",
              "offsetTimeUnit": "D",
              "offsetTimeValue": 0,
              "deadline": "string"
            },
            "penaltyCharge": {
              "chargeBase": "FullStay",
              "nights": 0,
              "amount": 0,
              "percent": 0
            }
          }
        ]
      }
    }
  ],
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}

Successful Response from Exchange Connection and Retail Rate Model(HTTP Status 200)

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotelId": "GATHI",
  "stayRange": {
    "checkin": "2028-01-01",
    "checkout": "2028-01-04"
  },
  "roomCriteria": {
    "roomCount": 2,
    "adultCount": 1,
    "childCount": 2,
    "childAges": [
      4,
      8
    ]
  },
  "productCandidate": {
    "roomId": "K1D",
    "rateId": "ODAD01"
  },
  "iata": "string",
  "roomRates": [
    {
      "inventory": 2,
      "isAfterPromotion": true,
      "promoteCode": "discount001",
      "roomId": "K1D",
      "roomName": "Double Room",
      "roomDescription": "Soak in city views in our Deluxe room, which features a well-appointed ensuite bathroom and up-to-date entertainment offerings.",
      "rateId": "ODAD01",
      "rateName": "Standard Rate",
      "rateDescription": "Standard Rate Includes Breakfast",
      "connectionType": "Exchange",
      "commission": {
        "value": 10,
        "type": "Percent"
      },
      "currency": "USD",
      "amountBeforeTax": [
        100,
        100,
        120
      ],
      "amountAfterTax": [
        110,
        110,
        130
      ],
      "mealPlan": "RO",
      "paymentType": "PayNow",
      "guarantee": {
        "guaranteeType": "CCG"
      },
      "fees": [
        {
          "dateRange": {
            "startDate": "2028-01-01",
            "endDate": "2028-01-04"
          },
          "fee": {
            "name": "Service Charge",
            "type": "Exclusive",
            "amount": 10,
            "amountType": "Percent",
            "chargeType": "PerRoomPerNight",
            "collectBy": "Distributor",
            "effectivePerson": 0
          }
        },
        {
          "dateRange": {
            "startDate": "2028-01-01",
            "endDate": "2028-01-04"
          },
          "fee": {
            "name": "City Tax",
            "type": "Exclusive",
            "amount": 5,
            "amountType": "Fix",
            "chargeType": "PerPersonPerNight",
            "collectBy": "Property",
            "effectivePerson": 0
          }
        }
      ],
      "cancelPolicy": {
        "code": "AD100P_100P",
        "description": "Non Refundable",
        "cancelPenalties": [
          {
            "noShow": true,
            "cancellable": true,
            "cancelDeadline": {
              "offsetTimeDropType": "BeforeArrival",
              "offsetTimeUnit": "D",
              "offsetTimeValue": 0,
              "deadline": "string"
            },
            "penaltyCharge": {
              "chargeBase": "FullStay",
              "nights": 0,
              "amount": 0,
              "percent": 0
            }
          }
        ]
      }
    }
  ],
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}

Successful Response from Exchange Connection and Net Rate Model(HTTP Status 200)

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotelId": "GATHI",
  "stayRange": {
    "checkin": "2028-01-01",
    "checkout": "2028-01-04"
  },
  "roomCriteria": {
    "roomCount": 2,
    "adultCount": 1,
    "childCount": 2,
    "childAges": [
      4,
      8
    ]
  },
  "productCandidate": {
    "roomId": "K1D",
    "rateId": "ODAD01"
  },
  "iata": "string",
  "roomRates": [
    {
      "inventory": 2,
      "isAfterPromotion": true,
      "promoteCode": "discount001",
      "roomId": "K1D",
      "roomName": "Double Room",
      "roomDescription": "Soak in city views in our Deluxe room, which features a well-appointed ensuite bathroom and up-to-date entertainment offerings.",
      "rateId": "ODAD01",
      "rateName": "Standard Rate",
      "rateDescription": "Standard Rate Includes Breakfast",
      "connectionType": "Exchange",
      "currency": "USD",
      "amountBeforeTax": [
        100,
        100,
        120
      ],
      "amountAfterTax": [
        110,
        110,
        130
      ],
      "suggestedTotalPrice": {
        "amountBeforeTax": 600,
        "amountAfterTax": 700
      },
      "mealPlan": "RO",
      "paymentType": "PayNow",
      "guarantee": {
        "guaranteeType": "CCG"
      },
      "fees": [
        {
          "dateRange": {
            "startDate": "2028-01-01",
            "endDate": "2028-01-04"
          },
          "fee": {
            "name": "Service Charge",
            "type": "Exclusive",
            "amount": 10,
            "amountType": "Percent",
            "chargeType": "PerRoomPerNight",
            "collectBy": "Distributor",
            "effectivePerson": 0
          }
        },
        {
          "dateRange": {
            "startDate": "2028-01-01",
            "endDate": "2028-01-04"
          },
          "fee": {
            "name": "City Tax",
            "type": "Exclusive",
            "amount": 5,
            "amountType": "Fix",
            "chargeType": "PerPersonPerNight",
            "collectBy": "Property",
            "effectivePerson": 0
          }
        }
      ],
      "cancelPolicy": {
        "code": "AD100P_100P",
        "description": "Non Refundable",
        "cancelPenalties": [
          {
            "noShow": true,
            "cancellable": true,
            "cancelDeadline": {
              "offsetTimeDropType": "BeforeArrival",
              "offsetTimeUnit": "D",
              "offsetTimeValue": 0,
              "deadline": "string"
            },
            "penaltyCharge": {
              "chargeBase": "FullStay",
              "nights": 0,
              "amount": 0,
              "percent": 0
            }
          }
        ]
      }
    }
  ],
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}

Error Response(HTTP Status 403)

{
  "error": "Key not authorized"
}

Error Response (HTTP Status 500)

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