Business Travel Suite Knowledge Base

TABLE OF CONTENTS

Availability API
Livecheck API
Book
Modify
Cancel
Query Reservation List
Query Reservation Detail

Change Log:

v 1.2.1

Add 'rateFlag' to the hotel product API, which indicates the product type.
- PUB: Public rates.
- CWD: Chain-wide discount. The products are dynamically changed and offer a certain percentage off the best available rates.
- RFP: Static negotiated rates. The rates are negotiated by corporations with suppliers and can be accessed via special corpCode.

v 1.2.0

Remove all the supplierCodein URL
Add modify API
Remove promotionassociation attributes
Remove addOnassociation attributes
Add securityCode field in /book API
Add vcc payment flag in /book and /modify API

Availability API

Availability API is used by distributors to check real-time availability to get all available rooms and rates for a single hotel. A call will be sent to the hotel supplier’s system to get real-time results.

POST /availability/ HTTP/1.1
URL: {endpoint}/availability/
Authorization:Bearer {apiKey}
Accept-Encoding: gzip Content-Encoding: gzip Content-Type: application/json;charset=utf-8

Request Example

{
  "header": {
    "supplierId": "string",
    "distributorId": "string",
    "version": "v1",
    "token": "be5b09acd91b45988f3f9dff595563f0"
  },
  "corpCode": "string",
  "hotelId": "GATHI",
  "stayRange": {
    "checkin": "2024-01-01",
    "checkout": "2024-01-04"
  },
  "roomCriteria": {
    "roomCount": 2,
    "adultCount": 1,
    "childCount": 2,
    "childAges": [
      4,
      8
    ]
  },
  "iata": "string",
  "loyaltyAccount": {
    "programCode": "BW",
    "accountId": "1234567890123457"
  },
 "corpAccount": {
    "corpProgramCode": "CR",
    "corpId": "A-1232"
  "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	/
loyaltyAccount	object	No	/	/
@programCode	string	Yes	Loyalty program code of the supplier	BW
@accountId	string	Yes	Loyalty program account ED	1234567890123457
corpAccount	object	/		/
@corpProgramCode	string	Yes	Corporate Hotel Program of hotel supplier	CR
@corpId	string	Yes	Corporate ID in the program account	A-1232
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": {
    "supplierId": "string",
    "distributorId": "string",
    "version": "v1",
    "token": "be5b09acd91b45988f3f9dff595563f0"
  },
  "hotelId": "GATHI",
  "stayRange": {
    "checkin": "2024-01-01",
    "checkout": "2024-01-04"
  },
  "roomCriteria": {
    "roomCount": 2,
    "adultCount": 1,
    "childCount": 2,
    "childAges": [
      4,
      8
    ]
  },
  "iata": "string",
  "roomRates": [
    {
      "roomId": "K1D",
      "rateId": "ODAD01",
      "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
            }
          }
        ]
      },
      "roomCriteria": {
        "roomCount": 2,
        "adultCount": 1,
        "childCount": 2,
        "childAges": [
          4,
          8
        ]
      },
      "inventory": 2
    }
  ],
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}

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
@roomId	string	Yes	Room ID in supplier system	10000101
@rateId	string	Yes	Rate ID in supplier system	123456
@rateFlag	enum	No	Product type. [PUB, CWD, RFP] PUB: Public rates CWD: Chain-wide discount rates RFP: Static negotiated rates	CWD
@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	/

Livecheck API

This api is used to check real-time availability before booking. It will be forward to the hotel supplier system to get real-time result.

OST /livecheck HTTP/1.1
URL: {endpoint}/livecheck
Authorization:Bearer {apiKey}
Accept-Encoding: gzip 
Content-Encoding: gzip 
Content-Type: application/json;charset=utf-8

Request Example

{
  "header": {
    "supplierId": "string",
    "distributorId": "string",
    "version": "v1",
    "token": "be5b09acd91b45988f3f9dff595563f0"
  },
  "corpCode": "string",
  "hotelId": "GATHI",
  "stayRange": {
    "checkin": "2024-01-01",
    "checkout": "2024-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"
  },
  "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 ]
productCandidate	object	Yes	/	/
@roomId	string	Yes	Room ID in supplier's system	K1D
@rateId	string	Yes	Rate ID in supplier's system	ODAD01
@rateFlag	enum	No	Product type. [PUB, CWD, RFP] PUB: Public rates CWD: Chain-wide discount rates RFP: Static negotiated rates	CWD
corpCode	string	No	Corp ID in distributor’s system	DIS
iata	string	No	IATA of distributor	/
loyaltyAccount	object	No	/	/
@programCode	string	Yes	Loyalty program code of the supplier	BW
@accountId	string	Yes	Loyalty program account ED	1234567890123457
corpAccount	object	/
@corpProgramCode	string	Yes	Corporate Hotel Program of hotel supplier	CR
@corpId	string	Yes	Corporate ID in the program account	A-1232
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": {
    "supplierId": "string",
    "distributorId": "string",
    "version": "v1",
    "token": "be5b09acd91b45988f3f9dff595563f0"
  },
  "hotelId": "GATHI",
  "stayRange": {
    "checkin": "2024-01-01",
    "checkout": "2024-01-04"
  },
  "roomCriteria": {
    "roomCount": 2,
    "adultCount": 1,
    "childCount": 2,
    "childAges": [
      4,
      8
    ]
  },
  "productCandidate": {
    "roomId": "K1D",
    "rateId": "ODAD01"
  },
  "iata": "string",
  "roomRates": [
    {
      "roomId": "K1D",
      "rateId": "ODAD01",
      "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
            }
          }
        ]
      },
      "roomCriteria": {
        "roomCount": 2,
        "adultCount": 1,
        "childCount": 2,
        "childAges": [
          4,
          8
        ]
      },
      "inventory": 2
    }
  ],
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}

Error Response(HTTP Status 403)

{
  "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 ]
productCandidate	object	No	/	/
@roomId	string	No	Room ID in supplier system	K1D
@rateId	string	No	Rate ID in supplier system	ODAD01
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
@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	For meal plan code, refer to the standard 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	The type of guarantee method, refer to the standard 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 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/	/
@code	string	Yes	Max Length: 128 Code of cancel policy	AD100P_100P
@description	string	No	Max Length: 1024 the description of the 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	/

Book

This API is used by distributors to book rooms. A call will be sent to the hotel supplier system to get a real-time confirmation.

POST /reservation/book HTTP/1.1
URL: {{endpoint}}/reservation/book/{supplierId}
Authorization:Bearer {apiKey}
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Request Example

{
  "header": {
    "supplierId": "string",
    "distributorId": "string",
    "version": "v1",
    "token": "be5b09acd91b45988f3f9dff595563f0"
  },
  "reservationIds": {
    "distributorResId": "C2084DFL0"
  },
  "iata": "string",
  "hotelId": "GATHI",
  "stayRange": {
    "checkin": "2024-01-01",
    "checkout": "2024-01-04"
  },
  "contactPerson": {
    "firstName": "James",
    "lastName": "Bond",
    "email": "007@james.com",
    "phone": "string",
    "address": "string"
  },
  "roomCriteria": {
    "roomCount": 2,
    "adultCount": 1,
    "childCount": 2,
    "childAges": [
      4,
      8
    ]
  },
  "total": {
    "amountBeforeTax": 640,
    "amountAfterTax": 700
  },
  "payment": {
    "cardCode": "VI",
    "cardNumber": "4111111111111111",
    "cardHolderName": "Sherlock Holmes",
    "expireDate": "119",
    "securityCode": "123"
  },
  "vcc": {
    "cardCode": "VI",
    "cardNumber": "4111111111111111",
    "cardHolderName": "Sherlock Holmes",
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "amount": 3000.05,
    "currency": "USD",
    "securityCode": "123"
  },
  "loyaltyAccount": {
    "programCode": "BW",
    "accountId": "1234567890123457"
  },
  "guests": [
    {
      "firstName": "James",
      "lastName": "Bond",
      "email": "007@james.com",
      "phone": "string",
      "address": "string",
      "age": 0,
      "gender": "Male",
      "birthday": "2024-01-01",
      "type": "Adult",
      "index": 1
    }
  ],
  "comments": [
    "no smoking",
    "high floor"
  ],
  "roomRates": [
    {
      "roomId": "K1D",
      "rateId": "ODAD01",
      "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
            }
          }
        ]
      }
    }
  ],
  "corpCode": "string",
  "threeDomainSecurity": {
    "cavv": "string",
    "eci": "string",
    "xid": "string",
    "threeDomainSecurityVersion": "string",
    "transactionId": "string",
    "merchantName": "string",
    "extensions": {
      "key1": "value1",
      "key2": "value2"
    }
  },
  "bookingToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}

Request Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@supplierId	string	Yes	Max Length: 32 The ID of the hotel supplier in DerbySoft's system	HILTON
@distributorId	string	Yes	Max Length: 32 The ID of distributor in DerbySoft's system	MOCK_DISTRIBUTOR
@version	string	Yes	Max Length: 20 Version of API	v4
@token	string	Yes	Max Length: 64 A unique ID to identify requests and responses, normally it should be UUID.	18393849028490234
reservationIds		Yes	/	/
@distributorResId	string	Yes	Reservation ID in distributor's system	C2084DFL0
corpCode	string	No	Corp ID in distributor’s system	DIS
iata	string	No	IATA	/
hotelId	string	Yes	Hotel ID in supplier's system	100001
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
contactPerson	object	Yes	/	/
@firstName	string	Yes	First Name	James
@lastName	string	Yes	Last Name	Bond
@email	string	No	Email	007@james.com
@phone	string	No	/	/
@address	string	No	/	/
roomCriteria	object	Yes	/	/
@roomCount	integer	Yes	Total room count per request	/
@adultCount	integer	Yes	Adult count per room	/
@childCount	integer	No	Child count per room	/
@childAges	array	No	For child ages for each child, the array size MUST be the same as the child count.	/
total	object	Yes	/	/
@amountBeforeTax	number	No	abbr. ABT It's required if AAT is not provided	640
@amountAfterTax	number	No	abbr. AAT It's required if ABT is not provided	700
payment	/	No	/	/
@cardCode	string	Yes	VI, MC, AX, etc. Card Code	VI
@cardNumber	string	Yes	Credit card number	4111111111111111
@cardHolderName	string	Yes	Cardholder name	Sherlock Holmes
@expireDate	string	Yes	It should be 2 digits for the month, 2 digits for the year, as "MMYY"	0119
@securityCode	string	No	Card verification value	123
loyaltyAccount	object	No	/	/
@programCode	string	Yes	Loyalty program code of the supplier	BW
@accountId	string	Yes	Loyalty program account ID	1234567890123457
corpAccount	object	/		/
@corpProgramCode	string	Yes	Corporate Hotel Program of hotel supplier	CR
@corpId	string	Yes	Corporate ID in the program account	A-1232
guests	array[object]	Yes	/
@firstName	string	Yes	First Name	James/
@lastName	string	Yes	Last Name	Bond
@email	string	No	Email	007@james.com
@phone	string	No	/	/
@address	string	No	/	/
@age	integer	No	Age of guest	/
@gender	enum	No	Gender of guest Enum: [Male, Female]	Male
@birthday	string	No	Birthday of guest format with yyyy-MM-dd	1970-12-20
@type	string	No	Type of guest, Adult, Child, or Infant Enum: [ Adult, Child, Infant ]	/
@index	integer	No	Indicate which guests will be allocated to which room. For one room reservation, the room index is 1 for all guests. For multi-room reservations, the index starts from 1 and the max room index is equal to the number of booked rooms.	index = 1, Indicate the guest will allocate to the first room. index = 2, Indicate the guest will allocate to the second room.
comments	array[string]	No	/	[ "no smoking", "high floor" ]
roomRates	array[object]	Yes	Min Items: 1 Max Items: 1 Meal plan, fee, and cancel policy are optional fields as some distributors do not support these in the API	/
@roomId	string	Yes	Room ID in supplier's system	10000101
@rateId	string	Yes	Rate ID in supplier's system	123456
@currency	string	Yes	Currency code [ISO-4217]	USD
@amountBeforeTax	array[number]	No	abbr. ABT The daily amount of rate without tax and fee. It's required if AAT is not provided	[ 100, 100, 120 ]
@amountAfterTax	array[number]	No	abbr. AAT The daily amount of rate with tax and fee. It's required if ABT is not provided	[ 110, 110, 130 ]
@mealPlan	string	No	Meal plan code, refer to the standard meal plan code list.	RO
@paymentType	enum	No	Indicates the product is prepaid to hotel (PayNow) or pay at hotel (PayLater). Enum: [ PayLater, PayNow ]	PayNow
roomRates/guarantee	object	No	Guarantee information for this room rate.	/
@guaranteeType	string	Yes	The type of guarantee method, refer to the standard 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 this fee will be charged based on how many persons, like an 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 defines what penalty will be a charge 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. '.	/
@code	string	Yes	Max Length: 128 code of cancel policy	AD100P_100P
@description	string	No	Max Length: 1024 the description of the cancellation 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	/	/	/	/
@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 times 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	It exists if the penalty charge is based on the night, like the first night.	/
@amount	number	No	It exists if the penalty charge is a flat charge, like USD 30.00.	/
@percent	number	No	It exists if the penalty charge is percent, like 15.5 means 15.5%.	/
bookingChannel	string	No	Sub-distributor ID	/
@date	string	Yes	format with yyyy-MM-dd	2022-01-01
@quantity	integer	Yes	/	1
@officeId	string	No	/	/
rate.ageQualifyingType	object	No	/	/
@type	enum	Yes	Enum: [Adult, Child]	Adult
@minAge	string	Yes	/	18
@maxAge	integer	Yes	/	18
rate.currency	string	Yes	/	USD
rate.amountBeforeTax	number	No	/	123.23
rate.amountAfterTax	number	No	/	134.34
threeDomainSecurity	object	No	/	/
@cavv	string	No	Cardholder Authentication Verification Value Information is retrieved from the 3DS provider when authentication is successful.	/
@eci	string	No	The electronic commerce indicator.	/
@xid	string	No	Transaction identifier for a 3DS Version 1 provider, assigned by the Directory Server to identify a single transaction.	/
@threeDomainSecurityVersion	string	No	Include this only for 3D Secure 2.	/
@transactionId	string	No	Transaction identifier for a 3DS Version 2 provider, assigned by the Directory Server to identify a single transaction.	/
@merchantName	string	No	Identifier of the merchant completing the 3DS transaction.	/
@channelCode	enum	No	Specify the collection channel of payment cards Enum: [TO, EC, MO, FA] Refer to: PSD2-Channel Code	EC
@exemptionType	enum	No	Determines which exemption was used by the Payment Service Provider (PSP) Enum: [SC, DA, TA, TB, LV] Refer to: PSD2-Exemption Type	SC
bookingToken	string	Yes	Booking token used for booking	eyJhbGciOiJIUzI1NiIsInR5cCI6Ik pXVCJ9.eyJzdWIiOiIxMjM0NTY3 ODkwIiwibmFtZSI6IkpvaG4gRG9lIi wiaWF0IjoxNTE2MjM5MDIyfQ .SflKxwRJSMeKKF2QT4fwpMeJf36PO k6yJV_adQssw5c
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	/
cardCode	string	Yes	the card scheme used by VCC issuers	VI-VISA MC- MasterCard AE- AMEX
cardNumber	string	Yes	the VCC card number	4111111111111111
cardHolderName	string	Yes	the card holder of the VCC	The VCC can be issued to a person or a company.
startDate	string	Yes	the date of activating VCC	yyyy-MM-dd
endDate	string	Yes	the date of terminating VCC	yyyy-MM-dd
amount	number	Yes	the amount loaded in VCC	3000.05
currency	string	Yes	the currency of the amount loaded	USD
securityCode	string	No	the CVV, CVC of the card	123

Response Example

Success Response (HTTP Status 200)

{
    "header": {
      "supplierId": "string",
      "distributorId": "string",
      "version": "v1.0.0",
      "token": "18393849028490234"
    },
    "reservationIds": {
      "distributorResId": "C2084DFL0",
      "derbyResId": "D15F893D34DF",
      "supplierResId": "89389494"
    },
    "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"
}

Response Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@supplierId	string	Yes	Max Length: 32 The ID of the hotel supplier in DerbySoft's system	HILTON
@distributorId	string	Yes	Max Length: 32 The ID of the distributor in DerbySoft's system	MOCK_DISTRIBUTOR
@version	string	Yes	Max Length: 20 Version of API	v1.0.0
@token	string	Yes	Max Length: 64 A unique ID to identify requests and responses, normally it should be UUID.	18393849028490234
reservationIds		Yes	/	/
@distributorResId	string	Yes	Reservation ID in distributor's system	C2084DFL0
@derbyResId	string	No	Reservation ID in DerbySoft system, this is a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
@supplierResId	string	No	Reservation ID in supplier's system	89389494
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

Modify

This api was used by distributor to modify an exist booking. It will be forwarded to the hotel supplier system to get a real-time confirmation.

POST

Request Example

{
  "header": {
    "supplierId": "string",
    "distributorId": "string",
    "version": "v1",
    "token": "be5b09acd91b45988f3f9dff595563f0"
  },
  "reservationIds": {
    "distributorResId": "C2084DFL0",
    "derbyResId": "D15F893D34DF",
    "supplierResId": "89389494"
  },
  "iata": "string",
  "hotelId": "GATHI",
  "stayRange": {
    "checkin": "2024-01-01",
    "checkout": "2024-01-04"
  },
  "contactPerson": {
    "firstName": "James",
    "lastName": "Bond",
    "email": "007@james.com",
    "phone": "string",
    "address": "string"
  },
  "roomCriteria": {
    "roomCount": 2,
    "adultCount": 1,
    "childCount": 2,
    "childAges": [
      4,
      8
    ]
  },
  "total": {
    "amountBeforeTax": 640,
    "amountAfterTax": 700
  },
  "payment": {
    "cardCode": "VI",
    "cardNumber": "4111111111111111",
    "cardHolderName": "Sherlock Holmes",
    "expireDate": "119",
    "securityCode": "123"
  },
  "loyaltyAccount": {
    "programCode": "BW",
    "accountId": "1234567890123457"
  },
 "corpAccount": {
    "corpProgramCode": "CR",
    "corpId": "A-1232"
  },
  "guests": [
    {
      "firstName": "James",
      "lastName": "Bond",
      "email": "007@james.com",
      "phone": "string",
      "address": "string",
      "age": 0,
      "gender": "Male",
      "birthday": "2024-01-01",
      "type": "Adult",
      "index": 1
    }
  ],
  "comments": [
    "no smoking",
    "high floor"
  ],
  "roomRates": [
    {
      "roomId": "K1D",
      "rateId": "ODAD01",
      "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
            }
          }
        ]
      }
    }
  ],
  "corpCode": "string",
  "threeDomainSecurity": {
    "cavv": "string",
    "eci": "string",
    "xid": "string",
    "threeDomainSecurityVersion": "string",
    "transactionId": "string",
    "merchantName": "string",
    "extensions": {
      "key1": "value1",
      "key2": "value2"
    }
  },
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}
"vcc": {
    "cardCode": "VI",
    "cardNumber": "4111111111111111",
    "cardHolderName": "Sherlock Holmes",
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "amount": 3000.05,
    "currency": "USD",
    "securityCode": "123"
  }

Request Specification

Attributes	Description	Required	Type	Example
header
header.token	An unique id to identiy request and response, normally it should be uuid	Yes	string	FA4AAAF482E16D2E6784C278821A1F0D
header.corpCode	Code of corp in distributor system	Yes	string	ABC
header.distributorCode	Distributor ID in DerbySoft's system	Yes	string	AA
header.version	Version of API	No	string	v1
distributorResId	Reservation id in distributor’s system (must be unique)	Yes	string	C2084DFL0
supplierCode	Code of supplier in DerbySoft’s system	Yes	string	IHG
corpCode	Corp code in the distributor’s system	No	string	IBM
hotelCode	Hotel code in the distributor’s system	Yes	string	710
supplierHotelCode	Hotel code in the supplier’s system	Yes	string	H710
checkin	Check-in date	Yes	string ($date)	2022-06-07
checkout	Check-out date	Yes	string ($date)	2022-06-08
roomCount	Total room count per request	Yes	integer	1
adultCount	Total adult count per room	Yes	integer	1
roomRates		Yes	object	/
roomRates.roomCode	Room code in the supplier’s system	Yes	string	RC1
roomRates.roomName	Room name in the supplier’s system	Yes	string	RC1
roomRates/ratePlanCode	Rate plan code in the supplier’s system	Yes	string	RP1
roomRates.ratePlanName	rate plan name in the supplier’s system	Yes	string	RP1
roomRates.currency	currency [ISO-4217]	Yes	string	USD
roomRates.dailyRates	Daily room rates	No	object	/
roomRates.dailyRates.amountBeforeTax	Daily amount before tax	No	string	100
rpomRates.dailyRates.amountAfterTax	Daily amount after tax	No	string	110
roomRates.paymentType	Indicates the product is prepaid to hotel(PayNow) or pay at hotel(PayLater)	No	enum [Pay Now, Pay Later]	Pay Now
roomRates.guaranteeType	Guarantee information	No	enum [CCG, GTTA, GTC, GTP, NG]	CCG
roomRates.mealPlan	Meal plan information	No	object	/
roomRates.mealPlan.code	Meal plan code	Yes	Enum [RO, BB, LO, DO, BL, HB, LD, AI, UNK ]	RO
roomRates.mealPlan.description	Meal plan description	No	object	/
roomRates.mealPlan.description.zh_CN	Meal plan description in Chinese	No	string	/
roomRates.mealPlan.description.en_US	Meal plan description in English	No	string	/
roomRates.cancelPolicy	Cancellation Information	No	object	/
roomRates.cancelPolicy.code	Cancellation policy code	No	string	AD100P_100P
roomRates.cancelPolicy.description	Cancellation policy description	No	string	Non-Refundable
roomRates.cancelPolicy.cancelPenalties	Cancellation penalties	No	object	/
roomRates.cancelPolicy.cancelPenalties.noShow	If true, it means the penaltyCharge applied for No-Show, and the cancellable, cancelDeadline will NOT exist	Yes	boolean	TRUE
roomRates.cancelPolicy.cancelPenalties.cancellable	It indicates cancellation is allowed or not. If false, it can not be cancelled. If true, the cancelDeadline will exists.	No	boolean	TRUE
roomRates.cancelPolicy.cancelPenalties.cancelDeadline		No	object	/
roomRates.cancelPolicy.cancelPenalties.cancelDeadline.offsetTimeDropType	An enumerated type indicates when the deadline drop time goes into effect.	No	Enum: [ BeforeArrival ]	BeforeArrival
roomRates.cancelPolicy.cancelPenalties.cancelDeadline.offsetTimeUnit	The cancellation deadline unit. D for days, H for hours	No	Enum: [ D,H ]	D
roomRates.cancelPolicy.cancelPenalties.cancelDeadline.offsetTimeValue	The cancellation deadline value	No	number	0
roomRates.cancelPolicy.cancelPenalties.cancelDeadline.deadline	Local deadline times allowed for cancellation, like 4 PM, 6 PM	No	string
roomRates.cancelPolicy.cancelPenalties.penaltyCharge	Cancellation penalties	Yes	object	/
roomRates.cancelPolicy.cancelPenalties.penaltyCharge.chargeBase	if FullStay, it will be a percentage or amount, if NightBased, the nights are required.	No	Enum: [ FullStay, NightBase ]	/
roomRates.cancelPolicy.cancelPenalties.penaltyCharge.nights	Exists if the penalty charge is based on the night, like the first night	No	number	/
roomRates.cancelPolicy.cancelPenalties.penaltyCharge.amount	Exists if the penalty charge is a flat charge, like USD 30.00	No	number	/
roomRates.cancelPolicy.cancelPenalties.penaltyCharge.percent	Exists if the penalty charge is percent, like 15.5 means 15.5%	No	number	/
roomRates.extenisons		No	string	/
totalAmountBeforeTax	Total amount before tax	No	string
totalAmountAfterTax	Total amount after tax	No	string
contactPerson		Yes	object
contactPerson.firstName	First name	No	string	James
contactPerson.lastName	Last name	No	string	Li
contactPerson.email	Email	No	string	007@james.com
contactPerson.phone	Phone	No	string	/
contactPerson.nationality	Nationality	No	string	CN
guests		Yes	object
guests.roomIndex	Indicates which guests will be allocated to which room.	Yes	integer	index = 1, Indicate the guest will allocate to the first room. index = 2, Indicate the guest will allocate to the second room.
guests.firstName	First name	No	string	James
guests.lastName	Last name	No	string	Li
guests.email	Guest email	No	string	007@james.com
guests.phone	Guest phone	No	string	/
guests.nationality	Guest nationality	No	string	CN
payment			object
payment.cardCode	Credit card code	Yes	string	VI, MC, AX
payment.cardNumber	Credit card number	Yes	string	4111111111111111
payment.cardHolderName	Credit card holder	Yes	string	Sherlock Holmes
payment.expireDate	Credit card expiration date	Yes	string (MMYY)	0119
loyaltyAccount			object
loyaltyAccount.programCode	Loyalty program of the supplier	No	string	BW
loyaltyAccount.accountId	Loyalty program account Id	No	string	123456789
corpAccount		No	object
@corpId	Corporate Hotel Program of hotel supplier	Yes	string	CR
@corpProgramCode	Corporate ID in the program account	Yes	string	A-1232
comments	Special remarks from guests	No	list	“high floor”, “non-smoking”
specialRequests	Special requests from distributor	No	list	“high floor”, “non-smoking”
extensions		No

Response Example

Success Response (HTTP Status 200)

{
  "header": {
    "token": "FA4AAAF482E16D2E6784C278821A1F0D",
    "corpCode": "string",
    "distributorCode": "ABC",
    "version": "v1"
  },
  "success": true,
  "error": {
    "code": "string",
    "message": "string"
  },
  "body": {
    "distributorResId": "C2084DFL0",
    "derbyResId": "D15F893D34DF",
    "supplierResId": 89389494,
    "extensions": {
      "k1": "v1",
      "k2": "v2"
    }
  }
}

Error Response (HTTP Status 401)

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

Error Response (HTTP Status 500)

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

Response Specification

Attributes	Description	Required	Type	Example
header
header.token	An unique id to identiy request and response, normally it should be uuid	Yes	string	FA4AAAF482E16D2E6784C278821A1F0D
header.corpCode	Code of corp in distributor system	Yes	string	ABC
header.distributorCode	Distributor ID in DerbySoft's system	Yes	string	AA
header.version	Version of API	No	string	v1
success	Indicates if the request is successful	Yes	boolean	TRUE
error	Error	No	object	/
error.code	Error code	No	string	Timeout
error.message	Error message	No	string	Internal System Error
body			object
distributorResId	Reservation ids in distributor’s system	Yes	string	C2084DFL0
derbyResId	Reservation ids in DerbySoft’s system	Yes	string	D15F893D34DF
supplierResId	Reservation ids in supplier’s system	Yes	string	89389494
extensions		No	string	[“k1”: “v1”] [“k2”: “v2”]

Cancel

This is an API for DerbySoft to call suppliers' systems to cancel a booking. Since DerbySoft does splitting on original reservations, the supplier should cancel the reservation by unique derbyResId or supplierResId.

POST /reservation/cancel HTTP/1.1
URL: {endpoint}/reservation/cancel/{supplierId}
Authorization: Bearer {apiKey}
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Request Example

{
    "header": {
        "supplierId": "string",
        "distributorId": "string",
        "version": "v1.0.0",
        "token": "18393849028490234"
    },
    "reservationIds": {
        "distributorResId": "C2084DFL0",
        "derbyResId": "D15F893D34DF",
        "supplierResId": "89389494"
    },
    "extensions": {
        "key1": "value1",
        "key2": "value2"
    }
}

Request Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@supplierId	string	Yes	Max Length: 32 The ID of hotel supplier in DerbySoft's system.	HILTON
@distributorId	string	Yes	Max Length: 32 The ID of the distributor in DerbySoft's system.	MOCK_DISTRIBUTOR
@version	string	Yes	Max Length: 20 Version of API	v1.0.0
@token	string	Yes	Max Length: 64 A unique ID to identify requests and responses, normally it should be UUID.	18393849028490234
reservationIds		Yes	/	/
@distributorResId	string	Yes	Reservation ID in distributor's system	C2084DFL0
@derbyResId	string	No	Reservation ID in Derbysoft's system, it's a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
@supplierResId	string	No	Reservation ID in supplier's system	89389494
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	{"key": "value"}

Response Example

Success Response (HTTP Status 200)

{
    "header": {
        "supplierId": "string",
        "distributorId": "string",
        "version": "v1.0.0",
        "token": "18393849028490234"
    },
    "reservationIds": {
        "distributorResId": "C2084DFL0",
        "derbyResId": "D15F893D34DF",
        "supplierResId": "89389494"
    },
    "cancellationId": "C89389494",
    "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"
}

Response Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@supplierId	string	Yes	Max Length: 32 The ID of hotel suppliers is in DerbySoft's system.	HILTON
@distributorId	string	Yes	Max Length: 32 The ID of the distributor in DerbySoft's system	MOCK_DISTRIBUTOR
@version	string	Yes	Max Length: 20 Version of API	v1.0.0
@token	string	Yes	Max Length: 64 A unique ID to identify requests and responses, normally it should be UUID.	18393849028490234
reservationIds	object	Yes	/	100001
@distributorResId	string	Yes	Reservation ID in distributor's system	C2084DFL0
@derbyResId	string	Yes	Reservation ID in Derbysoft's system, It's a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
@supplierResId	string	Yes	Reservation ID in supplier's system	89389494
cancellationId	string	Yes	Cancellation confirmation number in supplier's system	C89389494
extensions	object	No	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format)	/

Query Reservation List

This is an API to query a reservation list in DerbySoft's system and supplier's system with a timestamp range of the reservation's last modified date. It should be implemented by both DerbySoft and the supplier.

POST /reservations HTTP/1.1
URL: {{endpoint}}/reservations/(supplierId}
Authorization: Bearer 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Request Example

{
  "header": {
    "supplierId": "string",
    "distributorId": "string",
    "version": "v1.0.0",
    "token": "18393849028490234"
  },
  "dateRange": {
    "startDate": "2024-01-01",
    "endDate": "2024-01-04"
  },
  "hotelId": "GATHI"
}

Request Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/
@supplierId	string	Yes	Max Length: 32 The ID of the hotel supplier in DerbySoft's system	HILTON
@distributorId	string	Yes	Max Length: 32 The ID of the distributor in DerbySoft's system	MOCK_DISTRIBUTOR
@version	string	Yes	Max Length: 20 Version of API	v1.0.0
@token	string	Yes	Max Length: 64 A unique ID to identify requests and responses, normally it should be UUID.	18393849028490234
dateRange	/	/	/	/
@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
hotelId	string	No	Supplier hotel ID in DerbySoft's system	GATHI

Response Example

Success Response (HTTP Status 200)

{
  "header": {
    "supplierId": "string",
    "distributorId": "string",
    "version": "v1.0.0",
    "token": "18393849028490234"
  },
  "reservations": [
    {
      "reservationIds": {
        "distributorResId": "C2084DFL0",
        "derbyResId": "D15F893D34DF",
        "supplierResId": "89389494"
      },
      "iata": "string",
      "hotelId": "GATHI",
      "stayRange": {
        "checkin": "2024-01-01",
        "checkout": "2024-01-04"
      },
      "roomCriteria": {
        "roomCount": 2,
        "adultCount": 1,
        "childCount": 2,
        "childAges": [
          4,
          8
        ]
      },
      "total": {
        "amountBeforeTax": 640,
        "amountAfterTax": 700
      },
      "status": "Confirmed",
      "cancellationId": "C89389494",
      "result": "Successful",
      "failCause": {
        "errorCode": "string",
        "supplierErrorCode": "string",
        "errorMessage": "string"
      }
    }
  ]
}

Error Response (HTTP Status 403)

{
    "error": "Key not authorized"
}

Error Response (HTTP Status 500)

{
  "errorCode": "InvalidField",
  "errorMessage": "Invalid Message"
}

Response Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@supplierId	string	Yes	Max Length: 32 The ID of hotel supplier in DerbySoft's system	HILTON
@distributorId	string	Yes	Max Length: 32 The ID of the distributor in DerbySoft's system	MOCK_DISTRIBUTOR
@version	string	Yes	Max Length: 20 Version of API	v1.0.0
@token	string	Yes	Max Length: 64 A unique ID to identify requests and responses, normally it should be UUID.	18393849028490234
reservations	/	/	/	/
reservations/reservationIds	/	/	/	/
@distributorResId	string	Yes	Reservation ID in distributor's system	C2084DFL0
@derbyResId	string	Yes	Reservation ID in Derbysoft's system, this is a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
@supplierResId	string	Yes	Reservation ID in supplier's system	89389494
@iata	string	No	/	/
@hotelId	string	Yes	Hotel ID in supplier’s system	100001
reservations/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
reservations/roomCriteria	object	Yes	/
@roomCount	integer	Yes	Total room count per request
@adultCount	integer	Yes	Adult count per room
@childCount	integer	No	Child count per room
@childAges	array	No	For child ages for each child, array size MUST be the same as the child count.	[ 4, 8 ]
reservations/total	object	Yes	/	/
@amountBeforeTax	number	No	/	640
@amountAfterTax	number	No	/	700
@status	enum	Yes	Enum: [ Confirmed, Modified, Cancelled ] Status of reservation	/
cancellationId	string	No	Cancel confirmation number in supplier's system	C89389494
@result	enum	Yes	Enum: [ Successful, Failed, Processing ] Status of the reservation to send to supplier	/
reservations / failCause		No	/	/
@errorCode	string	Yes	Refer to Error Code Appendix	/
@supplierErrorCode	string	No	Error code from the supplier's system	/
@errorMessage	string	Yes	Error message	/

Query Reservation Detail

This API is used by distributors to query existing bookings. It can be used to check the reservation status of some timeout booking requests.

POST /reservation/detail HTTP/1.1
URL: {{endpoint}}/bts/api/reservation/detail/{supplierId}
Authorization: Bearer 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Request Example

{
  "header": {
    "supplierId": "string",
    "distributorId": "string",
    "version": "v1",
    "token": "be5b09acd91b45988f3f9dff595563f0"
  },
  "reservationIds": {
    "distributorResId": "C2084DFL0",
    "derbyResId": "D15F893D34DF",
    "supplierResId": "89389494"
  }
}

Request Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@supplierId	string	Yes	Max Length: 32 The ID of the hotel supplier in DerbySoft's system.	HILTON
@distributorId	string	Yes	Max Length: 32 The ID of the distributor in DerbySoft's system	MOCK_DISTRIBUTOR
@version	string	Yes	Max Length: 20 Version of API	v1.0.0
@token	string	Yes	Max Length: 64 A unique ID to identify requests and responses, normally it should be UUID.	18393849028490234
reservationIds		Yes	/	/
@distributorResId	string	Yes	Reservation ID in distributor's system	C2084DFL0
@derbyResId	string	No	Reservation ID in Derbysoft's system, it's a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
@supplierResId	string	No	Reservation ID in supplier's system	89389494

Response Example

Success Response (HTTP Status 200)

{
  "header": {
    "supplierId": "string",
    "distributorId": "string",
    "version": "v1",
    "token": "be5b09acd91b45988f3f9dff595563f0"
  },
  "reservations": [
    {
      "reservationIds": {
        "distributorResId": "C2084DFL0",
        "derbyResId": "D15F893D34DF",
        "supplierResId": "89389494"
      },
      "iata": "string",
      "hotelId": "GATHI",
      "stayRange": {
        "checkin": "2024-01-01",
        "checkout": "2024-01-04"
      },
      "roomCriteria": {
        "roomCount": 2,
        "adultCount": 1,
        "childCount": 2,
        "childAges": [
          4,
          8
        ]
      },
      "total": {
        "amountBeforeTax": 640,
        "amountAfterTax": 700
      },
      "loyaltyAccount": {
        "programCode": "BW",
        "accountId": "1234567890123457"
      },
      "comments": [
        "no smoking",
        "high floor"
      ],
      "roomRates": [
        {
          "roomId": "K1D",
          "rateId": "ODAD01",
          "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
                }
              }
            ]
          }
        }
      ],
      "bookingChannel": "string",
      "status": "Confirmed",
      "cancellationId": "C89389494",
      "result": "Successful",
      "failCause": {
        "errorCode": "string",
        "supplierErrorCode": "string",
        "errorMessage": "string"
      }
    }
  ]
}

Error Response (HTTP Status 403)

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

Error Response (HTTP Status 500)

{  "errorCode": "InvalidField",  
   "errorMessage": "Invalid Message"}

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
reservations	/	No	/	/
/reservationIds	/	/	/	/
@distributorResId	string	Yes	Reservation ID in distributor's system	C2084DFL0
@derbyResId	string	Yes	Reservation ID in DerbySoft system, this is a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
@supplierResId	string	Yes	Reservation ID in supplier's system	89389494
iata	string	No	/	/
hotelId	string	Yes	Hotel ID in supplier’s system	100001
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	/
@adultCount	integer	Yes	Adult count per room	/
@childCount	integer	No	Child count per room
@childAges	array	No	For child ages each child, the array size MUST be the same as the child count.	/
total	object	Yes	/	/
@amountBeforeTax	number	No	/	640
@amountAfterTax	number	No	/	700
loyaltyAccount	object	No	/	/
@programCode	string	Yes	Loyalty program code of the supplier	BW
@accountId	string	Yes	Loyalty program account ID	1234567890123457
comments	array[string]	No	/	[ "no smoking", "high floor" ]
roomRates	array[object]	Yes	Min Items: 1 Max Item: 1 Meal plan, fee, and cancel policy are optional fields as some distributors do not support these in the API.	/
@roomId	string	Yes	Room ID in supplier's system	10000101
@rateId	string	Yes	Rate ID in supplier's system	123456
@currency	string	Yes	Currency code [ISO-4217]	USD
@amountBeforeTax	array[number]	No	The daily amount rate without tax and fee	[ 100, 100, 120 ]
@amountAfterTax	array[number]	No	The daily amount of rate with tax and fee	[ 110, 110, 130 ]
@mealPlan	string	No	Meal plan code, refer to the standard 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	The type of guarantee method, refer to the standard 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	Indicates if 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		This means this fee 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 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.	/
@code	string		Max Length: 128 Code of cancel policy	AD100P_100P
@description	string		Max Length: 1024 The description of the cancellation policy	Non Refundable
cancelPolicy/cancelPenalties		Yes	Detail about the canceled Penalty	/
@noShow	boolean	Yes	If true, it means the penalty charge applied for No-Show, and the cancellable, cancelDeadline will NOT exist.	/
@cancellable	boolean	No	Indicates if cancellation is allowed or not. If false, it cannot be canceled. If true, the cancellation deadline will exist.	/
cancelPenalties/cancelDeadline	/	/	/	/
@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 times 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	It exists if the penalty charge is based on the night, like the first night.	/
@amount	number	No	It exists if the penalty charge is a flat charge, like USD 30.00.	/
@percent	number	No	It exists if the penalty charge is percent, like 15.5 means 15.5%	/
bookingChannel	string	No	Sub-distributor ID	/
status	enum	Yes	Enum: [ Confirmed, Modified, Cancelled ] The latest status of the reservation Confirmed - New reservation Modified - Modification Reservation Cancelled - Cancellation Reservation Please combine the status and result fields to determine the reservation whether successful, combination examples are as follows: Confirmed + Successful = Booking is successful Confirmed + Failed = Booking is failed Modified + Successful = Modification is successful Modified + Failed = Modification is failed Cancelled + Successful = Cancellation is successful Cancelled + Failed = Cancellation is failed	/
cancellationId	string	No	Cancellation confirmation number in suppliers' system	C89389494
result	enum	Yes	Enum: [ Successful, Failed, Processing ] result of the reservation to send to the supplier	/
reservations/failCause	/	No	/	/
@errorCode	string	Yes	Error Code Appendix	/
@supplierErrorCode	string	No	Error code from the supply system	/
@errorMessage	string	Yes	Error message

Reservation API

Availability API

Request Example

Request Specification

Response Example

Response Specification

Livecheck API

Request Example

Request Specification

Response Example

Response Specification

Book

Request Example

Request Specification

Response Example

Response Specification

Modify

Request Example

Request Specification

Response Example

Response Specification

Cancel

Request Example

Request Specification

Response Example

Response Specification

Query Reservation List

Request Example

Request Specification

Response Example

Response Specification

Query Reservation Detail

Request Example

Request Specification

Response Example

Response Specification