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


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"