Supplier Knowledge Base

Introduction

Promotion API is used by DerbySoft to get the list of promotions from Supply periodically. DerbySoft would calculate price while delivering ARI to a distributor. For reservation and live check, supply should apply for the promotions by themselves.

Hotel Promotion List (/promotion/hotels) - Get all hotels with promotions for a specific distributor.
Hotel Promotion Details (/promotion/hotel/{hotelId}}) - Get all available promotion rules of one hotel to a specific distributor.

TABLE OF CONTENTS

Introduction
Hotel Promotion List
Hotel Promotion Details

Hotel Promotion List

This is an API for DerbySoft to call the Supplier's system to get the hotel list with promotions for a specific distributor.

GET /promotion/hotels HTTP/1.1
URL: {{endpoint}}/promotion/hotels?distributorId={{distributorId}}
Authorization: 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Request Parameters

Name	Description	Required	Type	Example
distributorId	The ID of distributor in DerbySoft's system	Yes	string	HOTELBEDS

Response Example

Success Response (HTTP Status 200)

[
  {
    "hotelId": "100001",
    "distributorId": "GTA",
    "promotions": [
      {
        "promoteCode": "XXXX",
        "description": "Stay 4 nights and get 1 night for free"
      }
    ]
  }
]

Error Response (HTTP Status 500)

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

Response Specification

Attribute	Type	Required	Description	Example
hotelId	string	Yes	Hotel ID in supplier's system	100001
distributorId	string	Yes	Distributor ID in DerbySoft's system	GTA
promotions	array[object]	Yes	/	/
@promoteCode	string	Yes	Promote code, which could be used in @promoteCode of request in reservation & live check.	/
@description	string	No	Promotion description	Stay 4 nights and get 1 night for free

Hotel Promotion Details

This is an API for DerbySoft to call the supply system to get all promotion rules of one hotel to a specific distributor.

GET /promotion/hotel/{hotelId} HTTP/1.1
URL: {{endpoint}}/promotion/hotel/{hotelId}?distributorId={{distributorId}}
Authorization: 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Request Parameters

Name	Description	Required	Type	Example
hotelId	The ID of the hotel in the Supplier's system	Yes	string	100001
distributorId	The ID of the distributor in DerbySoft's system	Yes	string	HOTELBEDS

Response Example

Success Response (HTTP Status 200)

{
  "hotelId": "100001",
  "distributorId": "GTA",
  "multiPromotionsStrategy": "Sequence",
  "promotions": [
    {
      "promoteCode": "XXXX",
      "promoteName": "Mid-Annual Promotion",
      "description": "Stay 4 nights and get 1 night for free",
      "status": "Actived",
      "isCoupon": false,
      "sequence": 1,
      "productCandidates": [
        {
          "roomId": "K1D",
          "rateId": "ODAD01"
        }
      ],
      "bookWindow": {
        "startDate": "2018-01-01",
        "endDate": "2018-01-04",
        "eachDayStartTime": "00:00:00",
        "eachDayEndTime": "12:00:00",
        "excludedDate": [
          "2018-01-02",
          "2018-01-02"
        ]
      },
      "stayWindow": {
        "startDate": "2018-01-01",
        "endDate": "2018-01-04",
        "weekdays": "1111111",
        "excludedDate": [
          "2018-01-02",
          "2018-01-03"
        ]
      },
      "promoteType": "FreeNight",
      "basicDiscount": {
        "discountType": "Percent",
        "discountValue": 10,
        "rateApplied": false,
        "rateApplyOn": "AmountAfterTax",
        "addOnDescription": "a welcome drink, hot spring, shuttle bus are included in this promotion, please ask to hotel reception while checking-in",
        "restriction": {
          "minStayThrough": 1,
          "maxStayThrough": 4,
          "minRoomPerOrder": 0,
          "maxRoomPerOrder": 0
        }
      },
      "freeNight": {
        "stayNight": 4,
        "freeNight": 1,
        "recurring": true,
        "freeNightType": "LastNight",
        "rateApplied": false,
        "rateApplyOn": "AmountAfterTax",
        "addOnDescription": "a welcome drink, hot spring, shuttle bus are included in this promotion, please ask to hotel reception while checking-in",
        "restriction": {
          "minRoomPerOrder": 0,
          "maxRoomPerOrder": 0
        }
      },
      "lastMinute": {
        "discount": {
          "discountType": "Percent",
          "discountValue": 10
        },
        "rateApplied": false,
        "rateApplyOn": "AmountAfterTax",
        "addOnDescription": "a welcome drink, hot spring, shuttle bus are included in this promotion, please ask to hotel reception while checking-in",
        "restriction": {
          "minStayThrough": 1,
          "maxStayThrough": 4,
          "minAdvanceHour": 0,
          "maxAdvanceHour": 0,
          "minRoomPerOrder": 0,
          "maxRoomPerOrder": 0
        }
      },
      "earlyBooker": {
        "discount": {
          "discountType": "Percent",
          "discountValue": 10
        },
        "rateApplied": false,
        "rateApplyOn": "AmountAfterTax",
        "addOnDescription": "a welcome drink, hot spring, shuttle bus are included in this promotion, please ask to hotel reception while checking-in",
        "restriction": {
          "minStayThrough": 1,
          "maxStayThrough": 4,
          "minAdvanceDay": 0,
          "minRoomPerOrder": 0,
          "maxRoomPerOrder": 0
        }
      },
      "fixedPrice": {
        "type": "OccupancyRate",
        "occupancyRate": {
          "rate": [
            {
              "adultCount": 1,
              "childCount": 2,
              "amountBeforeTax": 502.19,
              "amountAfterTax": 623.23
            }
          ]
        },
        "commonRate": {
          "amountBeforeTax": 502.19,
          "amountAfterTax": 623.23
        },
        "rateApplied": false,
        "addOnDescription": "a welcome drink, hot spring, shuttle bus are included in this promotion, please ask to hotel reception while checking-in",
        "restriction": {
          "minStayThrough": 1,
          "maxStayThrough": 4,
          "minAdvanceDay": 0,
          "maxAdvanceDay": 0,
          "minAdvanceHour": 0,
          "maxAdvanceHour": 0,
          "minRoomPerOrder": 0,
          "maxRoomPerOrder": 0
        }
      },
      "giftPackage": {
        "description": "an extra dinner as gift is including in the price, please ask to hotel reception while checking-in",
        "restriction": {
          "minStayThrough": 1,
          "maxStayThrough": 4,
          "minRoomPerOrder": 0,
          "maxRoomPerOrder": 0
        }
      },
      "cancelPolicy": {
        "code": "AD100P_100P",
        "description": "Non Refundable"
      },
      "mealPlan": "RO",
      "extensions": {
        "key": "value"
      }
    }
  ]
}

Error Response (HTTP Status 500)

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

Response Specification

Attribute	Type	Required	Description	Example
hotelId	string	Yes	Hotel ID in supplier's system	100001
distributorId	string	Yes	Distributor id in DerbySoft's system	GTA
multiPromotionsStrategy	enum	Yes	Enum: [ Sequence, LowestPrice ] Status in supplier's system	Sequence
promotions	array [ojbect]	Yes	/	/
@promoteCode	string	Yes	Promotion code, which could be used in @promoteCode of request in reservation & live check.	/
@promoteName	string	No	Promotion name	Mid-Annual Promotion
@description	string	No	Promotion description	Stay 4 nights and get 1 night for free.
@status	enum	Yes	Enum: [ Actived, Deactived ] Status in supplier's system	Actived
@isCoupon	boolean	Yes	true: this promotion can be offered only when @promoteCode is valid in the request of reservation & live check. false: means this promotion can be offered even if the @promoteCode is empty in the request of reservation & live check. The flag indicates if it is a coupon promotion that requires @promoteCode. For distributors using the pull model, DerbySoft would apply the below logic while the distributor pulling ARI from DerbySoft. Only the promotions with “isCoupon”= false will be taken as candidates to be applied when making a multi-availability check.	false
@sequence	integer	No	Start from 0. It is required when @multiplePromotionsStrategy is Sequence. The promotion with the largest sequence number will be picked up if multiple promotions are available. Default is 0 if null.	1
promotions / productCandidates	array[object]	Yes	A product list to be applied with current promotion.	/
@roomId	string	Yes	Room ID in supplier's system	K1D
@rateId	string	Yes	Rate ID in supplier's system	ODAD01
promotions/bookWindow	object	No	A date range for the eligible booking date for this promotion. Leave it empty if there is no limitation to the booking window. The time is based on the hotel's local time.	/
@startDate	string	Yes	Start date of date range, format with yyyy-MM-dd.	2018-01-01
@endDate	string	Yes	End date of date range, format with yyyy-MM-dd.	2018-01-01
@eachDayStartTime	string	No	Start booking time of each day for promotion, format as "HH:MM: SS".	00:00:00
@eachDayEndTime	string	No	End booking time of each day for promotion, format as "HH:MM: SS". Leave both eachDayStartTime and eachDayEndTime empty if there is no limitation to the bookwindow at a specific time range within a day. It means the booking time range is across one day when eachDayEndTime is earlier than eachDayStartTime.	12:00:00
@excludedDate	array[string]	No	Excluded date of date range, format with yyyy-MM-dd.	[ "2018-01-02", "2018-01-02" ]
promotions/stayWindow	object	Yes	A date range for the eligible stay date for this promotion. The time is based on the hotel's local time.	/
@startDate	string	Yes	Start date of date range, format with yyyy-MM-dd.	2018-01-01
@endDate	string	Yes	End date of date range, format with yyyy-MM-dd.	2018-01-01
@weekdays	string	No	Specific days of the week that customers can stay for this promotion. Format for days is SMTWTFS starting with Sunday and 1 is for allowed to stay and 0 is for not allowed to stay. For example, a promotion for the stay only on Friday and Saturday would show as 0000011. Default is 1111111 if null.	1111111
@excludedDate	array[string]	No	Excluded date of the date range to stay for this promotion, format with yyyy-MM-dd.	[ "2018-01-02", "2018-01-02" ]
promotions/promoteType	enum	Yes	Enum: [ BasicDiscount, FreeNight, LastMinute, EarlyBooker, FixedPrice, GiftPackage ] Type of promotion. Only one of the enumerations can be chosen. Settings within the corresponding promotion type will be applied only	FreeNight
promotions/basicDiscount	object	No	/	/
@discountType	enum	Yes	Enum: [ Percent, Fix ] A fixed amount or a percentage markdown over the initial price	/
@discountValue	string	Yes	Value of discount, which could be a fixed discount or a percent discount according to discountType.	10
@rateApplied	boolean	Yes	Indicates this promotion is already applied to the rates of ARI or not. It's useful for DerbySoft or distributor to decide if a calculation is a need or not.	false
@rateApplyOn	enum	No	Enum: [ AmountAfterTax, AmountBeforeTax ] Indicates how to calculate the rate for this promotion if @rateApplied is false. It's required if @rateApplied is false. AmountAfterTax: calculate amountAfterTax in ARI according to this promotion. AmountBeforeTax: calculate amountBeforeTax in ARI according to this promotion (amountAfterTax should be re-calculated based on it and tax/fees of hotel API).	AmountAfterTax
@addOnDescription	string	No	Extra gifts, services, or add-ons can be provided here.	A welcome drink, hot spring, shuttle bus are included in this promotion, please ask hotel reception while checking in.
basicDiscount / restriction	object	No	/	/
@minStayThrough	integer	No	The minimum number of nights that customers must stay to be eligible for promotion, zero means no restriction.	1
@maxStayThrough	integer	No	The maximum number of nights that a customer must stay to be eligible for promotion, zero means no restriction.	4
@minRoomPerOrder	integer	No	The minimum number of rooms that customers must book to be eligible for the promotion.	/
@maxRoomPerOrder	integer	No	The maximum number of rooms that customers must book to be eligible for the promotion.	/
promotions/freeNight	object	No	/	/
stayNight	integer	Yes	/	4
freeNight	integer	Yes	/	1
recurring	boolean	Yes	A flag indicates if this promotion is recurring throughout the stay. For example, if this promotion is 1 night free for 4 nights staying, controls if this promotion would apply twice for an 8-night stay or just once.	true
freeNightType	string	Yes	Enum: [ FirstNight, LastNight ] Take 'stay 4 nights get 1 night for free as an example, recurring is true, the 4th night and the 8th night will be free.	LastNight
rateApplied	boolean	Yes	The flag indicates this promotion is already applied to the rates of ARI or not. It's useful for DerbySoft or distributor to decide if a calculation is a need or not.	false
rateApplyOn	enum	No	Enum: [ AmountAfterTax, AmountBeforeTax ] the tag indicates how to calculate the rate for this promotion if @rateApplied is false. It's required if @rateApplied is false. AmountAfterTax: calculate amountAfterTax in ARI according to this promotion. AmountBeforeTax: calculate amountBeforeTax in ARI according to this promotion(amountAfterTax should be re-calculated based on it and tax/fees of hotel API).	AmountAfterTax
addOnDescription	string	No	Extra gifts, services, or add-ons can be provided here.	A welcome drink, hot spring, shuttle bus are included in this promotion, please ask hotel reception while checking in.
freeNight / restriction	object	No	/	/
@minRoomPerOrder	integer	No	Minimal room amount per reservation for this promotion.	/
@maxRoomPerOrder	integer	No	Maximum room amount per reservation for this promotion.	/
promotions/lastMinute	object	No	The promotion for last-minute bookers.	/
lastMinute/discount	object	Yes	/	/
@discountType	enum	Yes	Enum: [ Percent, Fix ]	Fix
@discountValue	number	Yes	Value of discount, which could be a fixed discount or a percent discount according to discountType.	10
@rateApplied	boolean	Yes	The flag indicates this promotion is already applied to the rates of ARI or not. It's useful for DerbySoft or distributor to decide if a calculation is a need or not.	false
@rateApplyOn	enum	No	Enum: [ AmountAfterTax, AmountBeforeTax ] the tag indicates how to calculate the rate for this promotion if @rateApplied is false. It's required if @rateApplied is false. AmountAfterTax: calculate amountAfterTax in ARI according to this promotion. AmountBeforeTax: calculate amountBeforeTax in ARI according to this promotion (amountAfterTax should be re-calculated based on it and tax/fees of hotel API).	AmountAfterTax
@addOnDescription	string	No	Extra gifts, services, or add-ons can be provided here.	A welcome drink, hot spring, shuttle bus are included in this promotion, please ask hotel reception while checking in.
lastMinute/restriction	object	Yes	/	/
@minStayThrough	integer	No	The minimum number of nights that customers must stay to be eligible for promotion, zero means no restriction.	1
@maxStayThrough	integer	No	The maximum number of nights that a customer must stay to be eligible for promotion, zero means no restriction.	4
@minAdvanceHour	integer	No	Minimal hours to book in advance for this promotion, value greater than 23 is permitted.	/
@maxAdvanceHour	integer	Yes	Maximum hours to book in advance for this promotion, a value greater than 23 is permitted.	/
@minRoomPerOrder	integer	No	Minimal room amount per reservation for this promotion.	/
@maxRoomPerOrder	integer	No	Maximum room amount per reservation for this promotion.	/
promotions/earlyBooker	object	No	The promotion for early bookers.	/
earlyBooker/discount	object	No	/	/
@discountType	enum	Yes	Enum: [ Percent, Fix ] A fixed amount or a percentage markdown over the initial price	/
@discountValue	string	Yes	Value of discount, which could be a fixed discount or a percent discount according to discountType.	10
@rateApplied	boolean	Yes	The flag indicates this promotion is already applied to the rates of ARI or not. It's useful for DerbySoft or distributor to decide if a calculation is a need or not.	false
@rateApplyOn	enum	No	Enum: [ AmountAfterTax, AmountBeforeTax ] The tag indicates how to calculate the rate for this promotion if @rateApplied is false. It's required if @rateApplied is false. AmountAfterTax: calculate amountAfterTax in ARI according to this promotion. AmountBeforeTax: calculate amountBeforeTax in ARI according to this promotion(amountAfterTax should be re-calculated base on it and tax/fees of hotel API).	AmountAfterTax
@addOnDescription	string	No	Extra gifts, services, or add-ons can be provided here.	A welcome drink, hot spring, shuttle bus are included in this promotion, please ask hotel reception while check-in.
earlyBooker/restriction	object	No	/	/
@minStayThrough	integer	No	The minimum number of nights that customers must stay to be eligible for promotion, zero means no restriction.	1
@maxStayThrough	integer	No	The maximum number of nights that a customer must stay to be eligible for promotion, zero means no restriction.	4
@minAdvanceDay	integer	Yes	Minimal days to book in advance for this promotion, zero means no restriction.	/
@minRoomPerOrder	integer	No	The minimum number of rooms that customers must book to be eligible for the promotion.	/
@maxRoomPerOrder	integer	No	The maximum number of rooms that customers must book to be eligible for the promotion.	/
promotions/fixedPrice	object	No	Use a fixed price to override the original price, it is a common promotion type in China.	/
@type	object	Yes	Enum: [ OccupancyRate, CommonRate ] Indicates which rate model be used, OccupancyRate or CommonRate.	OccupancyRate
fixedPrice/occupancyRate	/	/	/	/
occupancyRate/rate	/	/	/	/
@adultCount	integer	Yes	/	1
@childCount	integer	No	/	2
@amountBeforeTax	number	No	/	522
@amountAfterTax	number	No	/	566
fixedPrice/commonRate	/	/	/	/
@amountBeforeTax	number	/	/	522
@amountAfterTax	number	No	/	566
@rateApplied	boolean	Yes	The flag indicates this promotion is already applied to the rates of ARI or not. It's useful for DerbySoft or distributor to decide if a calculation is a need or not.	false
@addOnDescription	string	No	Extra gifts, services, or add-ons can be provided here.	Welcome drink, hot spring, shuttle bus are included in this promotion, please ask hotel reception while check-in.
fixedPrice/restriction	object	No	/	/
@minStayThrough	integer	No	The minimum number of nights that customers must stay to be eligible for promotion, zero means no restriction.	1
@maxStayThrough	integer	No	The maximum number of nights that a customer must stay to be eligible for promotion, zero means no restriction.	4
@minAdvanceDay	integer	No	Minimal days to book in advance for this promotion, zero means no restriction.	/
@maxAdvanceDay	integer	No	Maximum days to book in advance for this promotion, zero means no restriction.	/
@minAdvanceDay	integer	No	Minimal days to book in advance for this promotion, zero means no restriction.	/
@minRoomPerOrder	integer	No	The minimum number of rooms that customers must book to be eligible for the promotion.	/
@minRoomPerOrder	integer	No	The minimum number of rooms that customers must book to be eligible for the promotion.	/
@maxRoomPerOrder	integer	No	The maximum number of rooms that customers must book to be eligible for the promotion.	/
promotions/giftPackage	object	No	/	/
@description	string	No	An extra dinner as a gift is including in the price, please ask hotel reception while checking in.	/
giftPackage/restriction	object	No	/	/
@minStayThrough	integer	No	The minimum number of nights that customers must stay to be eligible for promotion, zero means no restriction.	1
@maxStayThrough	integer	No	The maximum number of nights that a customer must stay to be eligible for promotion, zero means no restriction.	4
@minRoomPerOrder	integer	No	The minimum number of rooms that customers must book to be eligible for the promotion.	/
@maxRoomPerOrder	integer	No	The maximum number of rooms that customers must book to be eligible for the promotion.	/
promotions/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	/	MaxLength: 128 Code of canel policy	AD100P_100P
@description	string	No	MaxLength: 1024 The description of the cancel policy	Non Refundable
promotions/mealPlan	string	No	Meal plan code, ref to the standard meal plan code list. It will override the original product mealPlan.	RO
promotions/extensions	object	No	A common extension object for extra attributes like account, extra setting required by a distributor, etc.	"key": "value"

AgencyUSB-Promotion API

Introduction

Hotel Promotion List

Request Parameters

Response Example

Response Specification

Hotel Promotion Details

Request Parameters

Response Example

Response Specification