Distributor Knowledge Base

This is an optional API used to push supplier promotion activities to distributors periodically. The Promotion Push endpoint allows suppliers to send promotion details directly to distributors, keeping them informed of any promotional offers or discounts available for the hotels or products they are distributing.

In this model, suppliers can push the promotion information whenever there are new or updated promotions, ensuring that distributors always have access to the latest offers in real-time.

In the following sections, we will provide the schemas and examples for the Promotion API, outlining how promotion details are structured and how you can integrate this feature into your system.

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

Promotion Request Schema

Level	Field Name	Data Type	Required	Description	Example
1	header	object	Y	/	/
2	@supplierId	string	Y	The ID of hotel suppliers in DerbySoft's system. MaxLength: 32	HILTON
2	@distributorId	string	Y	The ID of distributor in DerbySoft's system. MaxLength: 32	GTA
2	@version	string	Y	Version of API. MaxLength: 20	v4
2	@token	string	Y	MaxLength: 64 A unique ID to identify request and response, normally it should be UUID.	18393849028490234
1	hotelPromotion	/	Y	/	/
2	@hotelId	string	Y	Hotel ID in supplier's system	100001
2	@supplierId	string	Y	The ID of hotel suppliers in DerbySoft's system. MaxLength: 32	Hilton
2	multiPromotionsStrategy	enum	Y	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
2	promotions	/	Y	/	/
3	@promoteCode	string	Y	Promotion code, which could be used in @promoteCode of request in reservation and live check.	/
3	@promoteName	string	N	Promotion name	Mid-Annual Promotion
3	@description	string	N	Promotion description	Stay 4 nights and get 1 night for free
3	@status	enum	Y	Enum: [Actived, Deactivated] status in supplier's system	Actived
3	@isCoupon	boolean	Y	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
3	@sequence	integer	N	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
3	productCandidates	/	Y	A product list to be applied with the current promotion.	/
4	@roomId	string	Y	Room ID in supplier's system	K1D
4	@rateId	string	Y	Rate ID in supplier's system	ODAD01
3	bookWindow	object	N	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.	/
4	@startDate	string	Y	Start date of date range expressed as YYYY-MM-DD	2028-01-01
4	@endDate	string	Y	End date of the date range expressed as YYYY-MM-DD	2028-01-01
4	@eachDayStartTime	string	N	Start booking time of each day for promotion, format as "HH:MM:SS".	00:00:00
4	@eachDayEndTime	string	N	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
4	@excludedDate	array[string]	N	Excluded date of date range, expressed as YYYY-MM-DD	[ "2028-01-02", "2028-01-02" ]
3	stayWindow	object	Y	A date range for the eligible stay date for this promotion. The time is based on the hotel's local time.	/
4	@startDate	string	Y	Start date of date range expressed as YYYY-MM-DD	2028-01-01
4	@endDate	string	Y	End date of the date range expressed as YYYY-MM-DD	2028-01-01
4	@weekdays	string	N	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
4	@excludedDate	array[string]	N	Excluded date of the date range to stay for this promotion, expressed as YYYY-MM-DD	[ "2028-01-02", "2028-01-02" ]
3	promoteType	enum	Y	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
3	basicDiscount	object	N	/	/
4	@discountType	enum	Y	Enum: [ Percent, Fix ] A fixed amount or a percentage markdown over the initial price.	/
4	@discountValue	string	Y	Value of the discount, which could be a fixed discount or percent discount according to discount type.	10
4	@rateApplied	boolean	Y	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
4	@rateApplyOn	enum	N	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
4	@addOnDescription	string	N	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.
4	restriction	object	N	/	/
5	@minStayThrough	integer	N	The minimum number of nights that a customer must stay to be eligible for promotion, zero means no restriction.	1
5	@maxStayThrough	integer	N	Maximum number of nights that customer must stay to be eligible for promotion, zero means no restriction	4
5	@minRoomPerOrder	integer	N	The minimum number of rooms that customers must book to be eligible for the promotion.	/
5	@maxRoomPerOrder	integer	N	The maximum number of rooms that customers must book to be eligible for the promotion.	/
3	freeNight	object	N	/	/
4	@stayNight	integer	Y	/	4
4	@freeNight	integer	Y	/	1
4	@recurring	boolean	Y	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
4	@freeNightType	string	Y	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
4	@rateApplied	boolean	Y	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
4	@rateApplyOn	enum	N	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
4	@addOnDescription	string	N	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.
4	restriction	object	N	/	/
5	@minRoomPerOrder	integer	N	Minimum room amount per reservation for this promotion.	/
5	@maxRoomPerOrder	integer	N	Maximum room amount per reservation for this promotion.	/
3	lastMinute	object	N	The promotion for last-minute bookers.	/
4	discount	object	Y	/	/
4	@discountType	enum	Y	Enum: [ Percent, Fix ]	Fix
4	@discountValue	number	Y	Value of the discount, which could be a fixed discount or percent discount according to discount type.	10
4	rateApplied	boolean	Y	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
4	rateApplyOn	enum	N	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
4	addOnDescription	string	N	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.
4	restriction	ojbect	Y	/	/
5	@minStayThrough	integer	N	The minimum number of nights that a customer must stay to be eligible for promotion, zero means no restriction.	1
5	@maxStayThrough	integer	N	The maximum number of nights that a customer must stay to be eligible for promotion, zero means no restriction.	4
5	@minAdvanceHour	integer	N	Minimum hours to book in advance for this promotion, a value greater than 23 is permitted.	/
5	@maxAdvanceHour	integer	Y	Maximum hours to book in advance for this promotion, a value greater than 23 is permitted.	/
5	@minRoomPerOrder	integer	N	Minimum room amount per reservation for this promotion.	/
5	@maxRoomPerOrder	integer	N	Maximum room amount per reservation for this promotion.	/
3	earlyBooker	object	N	The promotion for early bookers.	/
4	discount	ojbect	N	/	/
5	@discountType	enum	Y	Enum: [ Percent, Fix ] A fixed amount or a percentage markdown over the initial price.
5	@discountValue	string	Y	Value of the discount, which could be a fixed discount or percent discount according to discount type.	10
4	rateApplied	boolean	Y	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
4	rateApplyOn	enum	N	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
4	addOnDescription	string	N	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.
4	restriction	object	N	/	/
5	@minStayThrough	integer	N	The minimum number of nights that customers must stay to be eligible for promotion, zero means no restriction.	1
5	@maxStayThrough	integer	N	The maximum number of nights that a customer must stay to be eligible for promotion, zero means no restriction.	4
5	@minAdvanceDay	integer	Y	Minimum days to book in advance for this promotion, zero means no restriction.	/
5	@minRoomPerOrder	integer	N	The minimum number of rooms that customers must book to be eligible for the promotion.	/
5	@maxRoomPerOrder	integer	N	The maximum number of rooms that customers must book to be eligible for the promotion.	/
4	fixedPrice	object	N	Use a fixed price to override the original price, it is a common promotion type in China.	/
4	@type	object	Y	Enum: [ OccupancyRate, CommonRate ] Indicates which rate model be used, OccupancyRate or CommonRate.	OccupancyRate
4	occupancyRate	/	/	/	/
5	rate	/	/	/	/
6	@adultCount	integer	Y	/	1
6	@childCount	integer	N	/	2
6	@amountBeforeTax	number	N	Mandatory if AAT is not provided	522
6	@amountAfterTax	number	N	Mandatory if ABT is not provided	566
6	commonRate	/	N	/	/
6	@amountBeforeTax	number	N	Mandatory if AAT is not provided	522
6	@amountAfterTax	number	N	Mandatory if ABT is not provided	566
4	rateApplied	boolean	Y	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
4	addOnDescription	string	N	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.
4	restriction	object	N	/	/
5	@minStayThrough	integer	N	The minimum number of nights that customers must stay to be eligible for promotion, zero means no restriction.	1
5	@maxStayThrough	integer	N	The maximum number of nights that a customer must stay to be eligible for promotion, zero means no restriction.	4
5	@minAdvanceDay	integer	N	Minimum days to book in advance for this promotion, zero means no restriction.	/
5	@maxAdvanceDay	integer	N	Maximum days to book in advance for this promotion, zero means no restriction.	/
5	@minAdvanceDay	integer	N	Minimum days to book in advance for this promotion, zero means no restriction.	/
5	@minRoomPerOrder	integer	N	The minimum number of rooms that customers must book to be eligible for the promotion.	/
5	@minRoomPerOrder	integer	N	The minimum number of rooms that customers must book to be eligible for the promotion.	/
5	@maxRoomPerOrder	integer	N	The maximum number of rooms that customers must book to be eligible for the promotion.	/
3	giftPackage	object	N	/	/
4	@description	string	N	An extra dinner as a gift is included in the price, please ask at hotel reception while checking in.	/
4	restriction	object	N	/	/
5	@minStayThrough	integer	N	The minimum number of nights that customers must stay to be eligible for promotion, zero means no restriction.	1
5	@maxStayThrough	integer	N	The maximum number of nights that a customer must stay to be eligible for promotion, zero means no restriction.	4
5	@minRoomPerOrder	integer	N	The minimum number of rooms that customers must book to be eligible for the promotion.	/
5	@maxRoomPerOrder	integer	N	The maximum number of rooms that customers must book to be eligible for the promotion.	/
3	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	Y	MaxLength: 128 Code of cancel policy	AD100P_100P
4	@description	string	N	MaxLength: 1024 The description of the cancel policy	Non Refundable
4	cancelPenalties	array	Y	Detail about the cancel Penalty	/
5	@noShow	boolean	Y	If true, it means the penaltyCharge applied for No-Show, and the cancellable, cancelDeadline will NOT exist.	/
5	@cancellable	boolean	N	Indicates if cancel is allowed or not. If false, it cannot be canceled. If true, the cancelDeadline will exist.	/
5	cancelDeadline	/	N	/	/
6	@offsetTimeDropType	enum	N	An enumerated type indicating when the deadline drop time goes into effect. Enum: [ BeforeArrival ]	/
6	@offsetTimeUnit	enum	N	Enum: [ D, H ]	/
6	@offsetTimeValue	number	N	The number of offset times with the time unit.	/
6	@deadline	string	No	Local deadline times allowed for cancellation, like 4 PM, or 6 PM.	/
5	penaltyCharge	/	Y	/	/
6	@chargeBase	enum	N	Enum: [ FullStay, NightBase ] If FullStay, it will be percentage or amount, if NightBase, the nights are required.	/
6	@nights	number	N	Exists if the penalty charge is based on the night, like the first night.	/
6	@amount	number	N	Exists if the penalty charge is a flat charge, like USD 30.00.	/
6	@percent	number	N	Exists if the penalty charge is percent, like 15.5 means 15.5%.	/
3	mealPlan	string	N	For meal plan codes, refer to the standard meal plan code list. It will override the original product meal plan.	RO
3	extensions	object	N	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format)	"key": "value"
1	extension	/	N	A common extension object for extra attributes like account, extra setting required by a distributor, etc.	/

Promotion Request Example

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"
  }
}

Promotion Response Schema

Attribute	Type	Required	Description	Example
header	object	Y	/	/
@supplierId	string	Y	The ID of hotel suppliers in DerbySoft's system. MaxLength: 32	HILTON
@distributorId	string	Y	The ID of distributor in DerbySoft's system. MaxLength: 32	GTA
@version	string	Y	Version of API. MaxLength: 20	v4
@token	string	Y	A unique identifier is used for requests and responses, typically a UUID. Note that this is an echo token, not an access token.	18393849028490234
hotelId	string	Y	The ID of the hotel in the supplier's system	GATHI
extension	object	N	A common extension object for extra attributes like account, extra settings required by a distributor, etc.	{"key": "value"}

Promotion 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 403)

{
  "errorCode": "InvalidField",
  "errorMessage": "  Unauthorized token"
}

Error Response (HTTP Status 500)

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