Distributor Knowledge Base

The Query Reservation Detail API allows distributors to retrieve detailed information about existing bookings, including the current status of the reservation. The possible statuses include confirmed, modified, or cancelled, helping distributors track the progress and changes to the booking. This API provides a comprehensive view of individual reservations, allowing distributors to access key details such as guest information, room types, booking dates, and other important data. This API is essential for efficient reservation management, giving distributors the ability to stay informed about the status and details of each booking, enabling them to take appropriate actions when necessary.

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

Reservation Details 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. Max Length: 32	HILTON
2	@distributorId	string	Y	The ID of the distributor in DerbySoft's system MaxLength: 32	GTA
2	@version	string	Y	Max Length: 20 Version of API	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	reservationIds	object	Y	/	/
2	@distributorResId	string	Y	Distributor's reservation ID. Distributors should keep the ID unique on their system to avoid any potential issues caused by duplicate reservation IDs.	C2084DFL0
2	@derbyResId	string	N	Reservation ID in Derbysoft's system, it's a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
2	@supplierResId	string	N	Reservation ID in supplier's system	89389494

Reservation Details Request Example

Reservation Details Request Example

{
    "header": {
      "supplierId": "HILTON",
      "distributorId": "GTA",
      "version": "v4",
      "token": "18393849028490234"
    },
    "reservationIds": {
      "distributorResId": "C2084DFL0",
      "derbyResId": "D15F893D34DF",
      "supplierResId": "89389494"
    }
  }

Reservation Details 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. Max Length: 32	HILTON
2	@distributorId	string	Y	The ID of the distributor in DerbySoft's system MaxLength: 32	GTA
2	@version	string	Y	MaxLength: 20 version of API	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	reservations	array[object]	N	/	/
2	reservationIds	object	N	/	/
3	@distributorResId	string	Y	Distributor's reservation ID. Distributors should keep the ID unique on their system to avoid any potential issues caused by duplicate reservation IDs.	C2084DFL0
3	@derbyResId	string	Y	Reservation ID in DerbySoft system, This is a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
3	@supplierResId	string	Y	Reservation ID in supplier's system	89389494
2	iata	string	N	/	/
2	hotelId	string	Y	Hotel IDs provided by hotel suppliers, only the following characters are allowed. 1. Digits (0-9) 2. Uppercase letters (A-Z) 3. Hyphen ('-')	100001 GATHI 00016 PEP-B3T2 B8W7
2	stayRange	object	Y	/	/
3	@checkin	string	Y	Check in date expressed YYYY-MM-DD	2028-01-01
3	@checkout	string	Y	Check out date expressed YYYY-MM-DD	2028-01-04
2	roomCriteria	object	Y	/	/
3	@roomCount	integer	Y	Total room count per request	/
3	@adultCount	integer	Y	Adult count per room	/
3	@childCount	integer	N	Child count per room
3	@childAges	array	N	For child ages each child, the array size MUST be the same as the child count.	/
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	total	object	Y	/	/
3	@amountBeforeTax	number	N	/	640
3	@amountAfterTax	number	N	/	700
2	commission	object	N	If the Connection Type is "Exchange" and the Rate Model is "Retail", the node will be visible; otherwise, it will disappear.	/
3	@value	number	N	/	10
3	@type	enum	N	Commission type Enum: [Percent, Amount]	Percent
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	loyaltyAccount	object	N	/	/
3	@programCode	string	C	The loyalty program code of the supplier	BW
3	@accountId	string	C	Loyalty program account ID	1234567890123457
2	corpAccount	object	N	/	/
3	@corpProgramCode	string	C	Corporate Hotel Program of hotel supplier	CR
3	@corpId	string	C	Corporate ID in the program account	A-1232
2	promoteCode	string	N	The promotion code is defined by the hotel, the promotion code is required if making a reservation under the promotion.	/
2	comments	array[string]	N	Any preference or comment can be communicated in this field	[ "no smoking", "high floor" ]
2	roomRates	array[object]	Y	Min Item: 1 Max Item: 1 Meal plan, fee, and cancel policy are optional fields as some distributors do not support these in the API.	/
3	@roomId	string	Y	Room ID in supplier's system	10000101
3	@rateId	string	Y	Rate ID in supplier's system	123456
3	@currency	string	Y	Currency code [ISO-4217]	USD
3	@amountBeforeTax	array[number]	N	The daily amount rate without tax and fee	[ 100, 100, 120 ]
3	@amountAfterTax	array[number]	N	The daily amount of rate with tax and fee	[ 110, 110, 130 ]
3	@mealPlan	string	N	Meal plan code, refer to the standard meal plan code list.	RO
3	@paymentType	enum	N	Indicates the product is prepaid to the hotel (PayNow) or pay at the hotel (PayLater). Enum: [ PayLater, PayNow ]	PayNow
3	guarantee	object	N	Guarantee information for this room rate.	/
4	@guaranteeType	string	C	The type of guarantee method, refers to the standard guarantee type list.	CCG
3	fees	array[object]	N	Fee or tax by date range.	/
4	dateRange	object	C	/	/
4	@startDate	string	C	Start date of date range, format with yyyy-MM-dd	2028-01-01
5	@endDate	string	C	End date of date range, format with yyyy-MM-dd	2028-01-04
4	fee	object	C	/	/
5	@name	string	C	pattern: \w[\w\d]+ starts with a word character (letter, number, or underscore) followed by one or more word characters or digits.	Service Charge
5	@type	enum	C	Indicates if the fee or tax is included in the amount before tax or not. Enum: [ Inclusive, Exclusive ]	Exclusive
5	@amount	number	C	Amount value of fee or tax	10
5	@amountType	string	C	Indicates how to charge the tax, 10% per room per night in this example Enum: [ Fix, Percent ]	Percent
5	@chargeType	string	C	Enum: [ PerRoomPerNight, PerPersonPerNight, PerRoomPerStay, PerPersonPerStay ]	PerRoomPerNight
5	@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
5	@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
5	@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.	/
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.	/
4	@code	string	C	Max Length: 128 Code of cancel policy	AD100P_100P
4	@description	string	N	Max Length: 1024 The description of the cancellation policy	Non Refundable
4	cancelPenalties	array[object]	C	Details about the canceled Penalty	/
5	@noShow	boolean	C	If true, it means the penalty charge applied for No-Show, and the cancellable, cancelDeadline will NOT exist.	/
5	@cancellable	boolean	N	Indicates if cancellation is allowed or not. If false, it cannot be canceled. If true, the cancellation deadline will exist.	/
5	cancelDeadline	object	N	/	/
6	@offsetTimeDropType	enum	N	Enum: [ BeforeArrival ] An enumerated type indicates when the deadline drop time goes into effect.	/
6	@offsetTimeUnit	enum	N	Enum: [ D, H ]	/
6	@offsetTimeValue	number	N	The number of offset times with the time unit.	/
6	@deadline	string	N	Local deadline times allowed for cancellation, like 4 PM or 6 PM.	/
5	penaltyCharge	object	N	/	/
6	@chargeBase	enum	N	Enum: [ FullStay, NightBase ] If FullStay, it will be a percentage or amount. If NightBase, the nights are required.	/
6	@nights	number	N	It exists if the penalty charge is based on the night, like the first night.	/
6	@amount	number	N	It exists if the penalty charge is a flat charge, like USD 30.00.	/
6	@percent	number	N	It exists if the penalty charge is percent, like 15.5 means 15.5%	/
2	bookingChannel	string	N	Sub-distributor ID	/
2	productAddons	array[object]	N	Only available for some suppliers	/
3	@type	string	C	/	DisneyTicket
3	@code	string	C	/	/
3	@date	string	C	Expressed as YYYY-MM-DD	2022-01-01
3	@quantity	integer	C	/	1
3	@officeId	string	N	specific distributor office	/
3	rate	object	N	Only available for some suppliers	/
4	ageQualifyingType	object	N	/	/
5	@type	enum	C	Enum: [Adult, Child]	Adult
5	@minAge	integer	C	/	18
5	@maxAge	integer	C	/	18
3	currency	string	C	/	USD
3	amountBeforeTax	number	N	/	123.23
3	amountAfterTax	number	N	/	134.34
2	status	enum	Y	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 whether 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	/
2	cancellationId	string	N	Cancellation confirmation number in suppliers' system	C89389494
2	result	enum	Y	Enum: [ Successful, Failed, Processing ] result of the reservation to send to the supplier	/
2	failCause	object	N	Note: If the reservation fails, the node will be visible; otherwise, it will not appear.	/
3	@errorCode	string	Y	Error Code Appendix	/
3	@supplierErrorCode	string	N	Error code from the supply system	/
3	@errorMessage	string	Y	Error message	/

Reservation Details Response Example

Success Response (HTTP Status 200)

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "reservations": [
    {
      "reservationIds": {
        "distributorResId": "C2084DFL0",
        "derbyResId": "D15F893D34DF",
        "supplierResId": "89389494"
      },
      "iata": "string",
      "hotelId": "GATHI",
      "stayRange": {
        "checkin": "2028-01-01",
        "checkout": "2028-01-04"
      },
      "roomCriteria": {
        "roomCount": 2,
        "adultCount": 1,
        "childCount": 2,
        "childAges": [
          4,
          8
        ]
      },
      "connectionType": "Exchange",
      "total": {
        "amountBeforeTax": 640,
        "amountAfterTax": 700
      },
      "commission": {
        "value": 10,
        "type": "Percent"
      },
      "suggestedTotalPrice": {
        "amountBeforeTax": 600,
        "amountAfterTax": 700
      },
      "loyaltyAccount": {
        "programCode": "BW",
        "accountId": "1234567890123457"
      },
      "corpAccount": {
        "corpProgramCode": "CR",
        "corpId": "A-1232"
      },
      "promoteCode": "string",
      "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": "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
                }
              }
            ]
          }
        }
      ],
      "bookingChannel": "string",
      "productAddons": [
        {
          "type": "DisneyTicket",
          "code": "code",
          "date": "2028-01-01",
          "quantity": 1,
          "officeId": "string",
          "rate": {
            "ageQualifyingType": {
              "type": "Adult",
              "minAge": 18,
              "maxAge": 18
            },
            "currency": "USD",
            "amountBeforeTax": 123.23,
            "amountAfterTax": 134.34
          }
        }
      ],
      "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"
}

Query Reservation Details

Reservation Details Request Schema

Reservation Details Request Example

Reservation Details Response Schema

Reservation Details Response Example