Distributor Knowledge Base

TABLE OF CONTENTS

Introduction
Promotion

Introduction

This is an optional API that is used by DerbySoft to push supplier promotion activities to distributors periodically.

Promotion Push (/promotion/push): Push promotion details that suppliers offer to distributors.

Promotion

Push the promotion details that the suppliers offer to distributors.

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

Request Example

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotelPromotion": {
    "hotelId": "100001",
    "supplierId": "Hilton",
    "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",
          "cancelPenalties": [
            {
              "noShow": true,
              "cancellable": true,
              "cancelDeadline": {
                "offsetTimeDropType": "BeforeArrival",
                "offsetTimeUnit": "D",
                "offsetTimeValue": 0,
                "deadline": "string"
              },
              "penaltyCharge": {
                "chargeBase": "FullStay",
                "nights": 0,
                "amount": 0,
                "percent": 0
              }
            }
          ]
        },
        "mealPlan": "RO",
        "extensions": {
          "key1": "value1",
          "key2": "value2"
        }
      }
    ]
  },
  "extension": {
    "key1": "value1",
    "key2": "value2"
  }
}

Request Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@supplierId	string	Yes	MaxLength: 32 The ID of hotel supplier in DerbySoft's system.	HILTON
@distributorId	string	Yes	MaxLength: 32 The ID of distributor in DerbySoft's system.	GTA
@version	string	Yes	MaxLength: 20 Version of API	v4
@token	string	Yes	MaxLength: 64 A unique ID to identify request and response, normally it should be UUID.	18393849028490234
hotelPromotion	/	Yes	/	/
@hotelId	string	Yes	Hotel ID in supplier's system	100001
@supplierId	string	Yes	Supplier ID in DerbySoft's system	Hilton
multiPromotionsStrategy	enum	Yes	Enum: [ Sequence, LowestPrice ] Indicates the strategy used to select a promotion when multiple promotions are available. If Sequence, the sequence value will be given for each promotion in Promotion Detail.	Sequence
hotelPromotion/promotions	/	Yes	/	/
@promoteCode	string	Yes	Promotion code, which could be used in @promoteCode of request in reservation and 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, Deactivated] 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 and live check. false: means this promotion can be offered even @promoteCode is empty in the request of reservation and live check. The flag indicates if it is a coupon promotion that requires @promoteCode. For distributors using the pull model, DerbySoft will apply the below logic while the distributor is 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	/	Yes	A product list to be applied with the 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 booking window 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. 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. The 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 the discount, which could be a fixed discount or percent discount according to discount type.	10
@rateApplied	boolean	Yes	The flag indicates if this promotion is already applied to the rates of ARI or not. It's useful for DerbySoft or distributors 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, and shuttle bus are included in this promotion, please ask for hotel reception while checking in.
basicDiscount/restriction	object	No	/	/
@minStayThrough	integer	No	The minimum number of nights that a customer must stay to be eligible for promotion, zero means no restriction.	1
@maxStayThrough	integer	No	Maximum number of nights that 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 whether this promotion is already applied to the rates of ARI or not. It's useful for DerbySoft or distributors to decide if a calculation is needed 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 for hotel reception while checking in.
freeNight/restriction	object	No	/	/
@minRoomPerOrder	integer	No	Minimum 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 the discount, which could be a fixed discount or percent discount according to discount type.	10
lastMinute/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
lastMinute/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
lastMinute/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 for hotel reception while checking-in.
lastMinute/restriction	ojbect	Yes	/	/
@minStayThrough	integer	No	The minimum number of nights that a customer 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	Minimum hours to book in advance for this promotion, a 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	Minimum 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	ojbect	No	/	/
@discountType	enum	Yes	Enum: [ Percent, Fix ] A fixed amount or a percentage markdown over the initial price.
@discountValue	string	Yes	Value of the discount, which could be a fixed discount or percent discount according to discount type.	10
earlyBooker/rateApplied	boolean	Yes	The flag indicates if 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 needed or not.	false
earlyBooker/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
earlyBooker/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 for 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	Minimum 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/occupancyRat	/	/	/	/
occupancyRate / rate	/	/	/	/
@adultCount	integer	Yes	/	1
@childCount	integer	No	/	2
@amountBeforeTax	number	No	/	522
@amountAfterTax	number	No	/	566
fixedPrice/commonRate	/	No	/	/
@amountBeforeTax	number	No	/	522
@amountAfterTax	number	No	/	566
fixedPrice/rateApplied	boolean	Yes	The flag indicates if 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 needed or not.	false
fixedPrice/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 for 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	Minimum 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	Minimum 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 included in the price, please ask at 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	Yes	MaxLength: 128 Code of cancel policy	AD100P_100P
@description	string	No	MaxLength: 1024 The description of the cancel policy	Non Refundable
cancelPolicy/cancelPenalties	array	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 if cancel is allowed or not. If false, it cannot be canceled. If true, the cancelDeadline will exist.	/
cancelPenalties/cancelDeadline	/	No	/	/
@offsetTimeDropType	enum	No	An enumerated type indicating when the deadline drop time goes into effect. Enum: [ BeforeArrival ]	/
@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	/	Yes	/	/
@chargeBase	enum	No	Enum: [ FullStay, NightBase ] If FullStay, it will be 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%.	/
promotions/mealPlan	string	No	For meal plan codes, refer to the standard meal plan code list. It will override the original product meal plan.	RO
promotions/extensions	object	No	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format)	"key": "value"
extension	/	No	A common extension object for extra attributes like account, extra setting required by a distributor, etc.	/

Response Example

Success Response (HTTP Status 200)

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotelId": "GATHI",
  "extension": {
    "key1": "value1",
    "key2": "value2"
  }
}

Error Response (HTTP Status 500)

{
  "errorCode": "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 ID of distributor in DerbySoft's system	GTA
@version	string	Yes	MaxLength: 20 Version of API	v4
@token	string	Yes	MaxLength: 64 A unique ID to identify requests and responses, normally it should be UUID.	18393849028490234
hotelId	string	Yes	The ID of the hotel in the supplier's system	GATHI
extension	object	No	A common extension object for extra attributes like account, extra setting required by a distributor, etc.	{"key": "value"}

English

BookingUSB-Promotion API

Introduction

Promotion

Request Example

Response Example

Response Specification