Promotion API

1. Overview

The Promotion API allows Channel Managers to

Create new promotion
Update existing promotion
Activate or Deactivate promotion (Toggle)
Retrieve promotion

1.1. Version information

Version : 1.0.0

1.2. URI scheme

Host : content-push.agoda.com
BasePath : /
Schemes : HTTPS, HTTP

1.3. Tags

ErrorCodes
Promotion
PromotionRetrieve
PromotionToggle

2. Change logs

Release Date	Version	Change logs
2020-10-30	1.0.0	Promotion API will now allow you to create and modify promotions for Agoda. Following features are available in this version Create and update new promotions Fetch promotions Active/Deactive promotions

Release Date

Version

Change logs

2020-10-30

1.0.0

Promotion API will now allow you to create and modify promotions for Agoda.

Following features are available in this version

Create and update new promotions
Fetch promotions
Active/Deactive promotions

3. Security

3.1. apiKey

Type : apiKey
Name : apiKey
In : HEADER

4. Paths

4.1. Create/Update Promotion

POST /cm/promotion

4.1.1. Description

This section outlines the feature to create and update a promotion. All promotion types share many common elements and attributes. Promotion types EarlyBird, ExpressTonight, FreeNights, and LastNight each has unique elements that are specified in the “5. Definitions” section below.

4.1.2. Body parameter

HotelPromotion_RQ must be supplied.

Name : body
Flags : required
Type : HotelPromotion_RQ

4.1.3. Responses

HTTP Code	Description	Schema
200	The promotion has been created/updated successfully	No Content
400	The request content was malformed	No Content
401	The supplier was unauthorized	No Content

HTTP Code

Description

Schema

200

The promotion has been created/updated successfully

No Content

400

The request content was malformed

No Content

401

The supplier was unauthorized

No Content

4.1.4. Consumes

application/xml

4.1.5. Produces

application/xml

4.1.6. Tags

Promotion

4.1.7. Security

Type	Name
apiKey	apiKey

Type

Name

apiKey

4.1.8. Example HTTP request

Request path

/cm/promotion

Request for create Customized promotion type

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RQ Timestamp="1605141841949">
  <Promotion PromotionType="Customized" PromotionName="Customized Promotion example" PromotionExternalId="CTM001" HotelId="203103755"/>
  <SaleDateRange Start="2021-01-01" End="2021-03-05"/>
  <StayDateRange Start="2021-02-01" End="2021-06-05"/>
  <MinNoOfRooms>2</MinNoOfRooms>
  <BlackoutDateRange>
    <DateRange Start="2021-03-15" End="2021-03-30"/>
    <DateRange Start="2021-06-01" End="2021-06-03"/>
  </BlackoutDateRange>
  <LengthOfStay Min="1" Max="7"/>
  <BookOn>
    <Day>Sunday</Day>
    <Day>Tuesday</Day>
    <Day>Thursday</Day>
    <Day>Saturday</Day>
  </BookOn>
  <StayOn>
    <Day>Monday</Day>
    <Day>Wednesday</Day>
    <Day>Friday</Day>
  </StayOn>
  <CheckinOn>
    <Day>Wednesday</Day>
    <Day>Thursday</Day>
    <Day>Friday</Day>
    <Day>Saturday</Day>
  </CheckinOn>
  <BookingTime From="12:00" To="22:00"/>
  <IsStackable>false</IsStackable>
  <Discount>
    <PercentPerNight NightType="SpecificDOW">
      <Value>25.0</Value>
      <Value>15.0</Value>
      <Value>0.0</Value>
      <Value>0.0</Value>
      <Value>0.0</Value>
      <Value>0.0</Value>
      <Value>10.0</Value>
    </PercentPerNight>
  </Discount>
  <CancellationPolicy Id="963"/>
  <Channels>
    <Channel Id="1"/>
    <Channel Id="7"/>
  </Channels>
  <CustomerSegments>
    <CustomerSegment Id="0"/>
  </CustomerSegments>
  <RatePlans>
    <RatePlan Id="3371504"/>
  </RatePlans>
  <Rooms>
    <Room Id="1201489087"/>
  </Rooms>
</HotelPromotion_RQ>

Request for create EarlyBird promotion type

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RQ Timestamp="1605141841949">
  <Promotion PromotionType="EarlyBird" PromotionName="EarlyBird Promotion - New Year 2022" PromotionExternalId="EBNY2021" HotelId="203103755"/>
  <EarlyBird MinAdvPurchase="5"/>
  <SaleDateRange Start="2021-01-01" End="2021-06-05"/>
  <StayDateRange Start="2021-12-01" End="2022-01-05"/>
  <MinNoOfRooms>2</MinNoOfRooms>
  <BlackoutDateRange>
    <DateRange Start="2021-12-31" End="2022-01-01"/>
    <DateRange Start="2021-12-25" End="2021-12-26"/>
  </BlackoutDateRange>
  <LengthOfStay Min="1" Max="7"/>
  <BookOn>
    <Day>Sunday</Day>
    <Day>Tuesday</Day>
    <Day>Thursday</Day>
    <Day>Saturday</Day>
  </BookOn>
  <StayOn>
    <Day>Monday</Day>
    <Day>Wednesday</Day>
    <Day>Friday</Day>
  </StayOn>
  <CheckinOn>
    <Day>Wednesday</Day>
    <Day>Thursday</Day>
    <Day>Friday</Day>
    <Day>Saturday</Day>
  </CheckinOn>
  <BookingTime From="12:00" To="22:00"/>
  <IsStackable>false</IsStackable>
  <Discount>
    <AmountPerNight NightType="SpecificNight">
      <Value>100.0</Value>
      <Value>110.0</Value>
      <Value>120.0</Value>
      <Value>0.0</Value>
      <Value>0.0</Value>
      <Value>0.0</Value>
      <Value>115.0</Value>
    </AmountPerNight>
  </Discount>
  <CancellationPolicy Id="963"/>
  <Channels>
    <Channel Id="1"/>
    <Channel Id="7"/>
  </Channels>
  <CustomerSegments>
    <CustomerSegment Id="0"/>
  </CustomerSegments>
  <RatePlans>
    <RatePlan Id="3371503"/>
  </RatePlans>
  <Rooms>
    <Room Id="1201489087"/>
  </Rooms>
</HotelPromotion_RQ>

Request for create ExpressTonight promotion type

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RQ Timestamp="1605141841949">
  <Promotion PromotionType="ExpressTonight" PromotionName="ExpressTonight Promotion" PromotionExternalId="EXPRESS001" HotelId="203103755"/>
  <SaleDateRange Start="2020-11-19" End="2020-11-20"/>
  <StayDateRange Start="2020-11-19" End="2020-11-21"/>
  <MinNoOfRooms>2</MinNoOfRooms>
  <LengthOfStay Min="1" Max="3"/>
  <BookingTime From="12:00" To="22:00"/>
  <IsStackable>false</IsStackable>
  <Discount>
    <ExpressTonight Value="3000.0" ChannelDiscount="true"/>
  </Discount>
  <CancellationPolicy Id="963"/>
  <Channels>
    <Channel Id="1"/>
    <Channel Id="7"/>
  </Channels>
  <CustomerSegments>
    <CustomerSegment Id="0"/>
  </CustomerSegments>
  <RatePlans>
    <RatePlan Id="0"/>
  </RatePlans>
  <Rooms>
    <Room Id="0"/>
  </Rooms>
</HotelPromotion_RQ>

Request for create LastMinute promotion type

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RQ Timestamp="1605141841949">
  <Promotion PromotionType="LastMinute" PromotionName="LastMinute Promotion" PromotionExternalId="LMN001" HotelId="203103755"/>
  <LastMinute MaxAdvPurchase="2"/>
  <SaleDateRange Start="2021-01-01" End="2021-03-05"/>
  <StayDateRange Start="2021-02-01" End="2021-06-05"/>
  <MinNoOfRooms>2</MinNoOfRooms>
  <BlackoutDateRange>
    <DateRange Start="2021-03-15" End="2021-03-30"/>
    <DateRange Start="2021-06-01" End="2021-06-03"/>
  </BlackoutDateRange>
  <LengthOfStay Min="1" Max="7"/>
  <BookOn>
    <Day>Sunday</Day>
    <Day>Tuesday</Day>
    <Day>Thursday</Day>
    <Day>Saturday</Day>
  </BookOn>
  <StayOn>
    <Day>Monday</Day>
    <Day>Wednesday</Day>
    <Day>Friday</Day>
  </StayOn>
  <CheckinOn>
    <Day>Wednesday</Day>
    <Day>Thursday</Day>
    <Day>Friday</Day>
    <Day>Saturday</Day>
  </CheckinOn>
  <BookingTime From="12:00" To="22:00"/>
  <IsStackable>false</IsStackable>
  <Discount>
    <AmountPerBooking Value="1500.0"/>
  </Discount>
  <CancellationPolicy Id="963"/>
  <Channels>
    <Channel Id="1"/>
    <Channel Id="7"/>
  </Channels>
  <CustomerSegments>
    <CustomerSegment Id="0"/>
  </CustomerSegments>
  <RatePlans>
    <RatePlan Id="0"/>
  </RatePlans>
  <Rooms>
    <Room Id="0"/>
  </Rooms>
</HotelPromotion_RQ>

Request for create LongStay promotion type

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RQ Timestamp="1605141841949">
  <Promotion PromotionType="LongStay" PromotionName="LongStay Promotion" PromotionExternalId="LONG001" HotelId="203103755"/>
  <SaleDateRange Start="2021-01-01" End="2021-03-05"/>
  <StayDateRange Start="2021-02-01" End="2021-06-05"/>
  <MinNoOfRooms>2</MinNoOfRooms>
  <BlackoutDateRange>
    <DateRange Start="2021-03-15" End="2021-03-30"/>
    <DateRange Start="2021-06-01" End="2021-06-03"/>
  </BlackoutDateRange>
  <LengthOfStay Min="3" Max="7"/>
  <BookOn>
    <Day>Sunday</Day>
    <Day>Tuesday</Day>
    <Day>Thursday</Day>
    <Day>Saturday</Day>
  </BookOn>
  <StayOn>
    <Day>Monday</Day>
    <Day>Wednesday</Day>
    <Day>Friday</Day>
  </StayOn>
  <CheckinOn>
    <Day>Wednesday</Day>
    <Day>Thursday</Day>
    <Day>Friday</Day>
    <Day>Saturday</Day>
  </CheckinOn>
  <BookingTime From="12:00" To="22:00"/>
  <IsStackable>false</IsStackable>
  <Discount>
    <FreeNights Value="2" IsRecurring="false"/>
  </Discount>
  <CancellationPolicy Id="963"/>
  <Channels>
    <Channel Id="1"/>
    <Channel Id="7"/>
  </Channels>
  <CustomerSegments>
    <CustomerSegment Id="0"/>
  </CustomerSegments>
  <RatePlans>
    <RatePlan Id="0"/>
  </RatePlans>
  <Rooms>
    <Room Id="0"/>
  </Rooms>
</HotelPromotion_RQ>

Request for create SeventyTwoHours promotion type

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RQ Timestamp="1605141841949">
  <Promotion PromotionType="SeventyTwoHours" PromotionName="SeventyTwoHours Promotion" PromotionExternalId="72HRS001" HotelId="203103755"/>
  <SaleDateRange Start="2021-01-01" End="2021-03-05"/>
  <StayDateRange Start="2021-02-01" End="2021-06-05"/>
  <MinNoOfRooms>2</MinNoOfRooms>
  <BlackoutDateRange>
    <DateRange Start="2021-03-15" End="2021-03-30"/>
    <DateRange Start="2021-06-01" End="2021-06-03"/>
  </BlackoutDateRange>
  <LengthOfStay Min="1" Max="7"/>
  <BookOn>
    <Day>Sunday</Day>
    <Day>Tuesday</Day>
    <Day>Thursday</Day>
    <Day>Saturday</Day>
  </BookOn>
  <StayOn>
    <Day>Monday</Day>
    <Day>Wednesday</Day>
    <Day>Friday</Day>
  </StayOn>
  <CheckinOn>
    <Day>Wednesday</Day>
    <Day>Thursday</Day>
    <Day>Friday</Day>
    <Day>Saturday</Day>
  </CheckinOn>
  <BookingTime From="12:00" To="22:00"/>
  <IsStackable>false</IsStackable>
  <Discount>
    <AmountPerBooking Value="400.0"/>
  </Discount>
  <CancellationPolicy Id="963"/>
  <Channels>
    <Channel Id="1"/>
    <Channel Id="7"/>
  </Channels>
  <CustomerSegments>
    <CustomerSegment Id="0"/>
  </CustomerSegments>
  <RatePlans>
    <RatePlan Id="0"/>
  </RatePlans>
  <Rooms>
    <Room Id="0"/>
  </Rooms>
</HotelPromotion_RQ>

Request for create SpecialOffer promotion type

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RQ Timestamp="1605141841949">
  <Promotion PromotionType="SpecialOffer" PromotionName="SpecialOffer Promotion" PromotionExternalId="SPO001" HotelId="203103755"/>
  <SaleDateRange Start="2021-01-01" End="2021-03-05"/>
  <StayDateRange Start="2021-02-01" End="2021-06-05"/>
  <MinNoOfRooms>2</MinNoOfRooms>
  <BlackoutDateRange>
    <DateRange Start="2021-03-15" End="2021-03-30"/>
    <DateRange Start="2021-06-01" End="2021-06-03"/>
  </BlackoutDateRange>
  <LengthOfStay Min="1" Max="7"/>
  <BookOn>
    <Day>Sunday</Day>
    <Day>Tuesday</Day>
    <Day>Thursday</Day>
    <Day>Saturday</Day>
  </BookOn>
  <StayOn>
    <Day>Monday</Day>
    <Day>Wednesday</Day>
    <Day>Friday</Day>
  </StayOn>
  <CheckinOn>
    <Day>Wednesday</Day>
    <Day>Thursday</Day>
    <Day>Friday</Day>
    <Day>Saturday</Day>
  </CheckinOn>
  <BookingTime From="12:00" To="22:00"/>
  <IsStackable>false</IsStackable>
  <Discount>
    <AmountPerBooking Value="4500.0"/>
  </Discount>
  <CancellationPolicy Id="963"/>
  <Channels>
    <Channel Id="1"/>
    <Channel Id="7"/>
  </Channels>
  <CustomerSegments>
    <CustomerSegment Id="0"/>
  </CustomerSegments>
  <RatePlans>
    <RatePlan Id="0"/>
  </RatePlans>
  <Rooms>
    <Room Id="0"/>
  </Rooms>
</HotelPromotion_RQ>

Request for update Customized promotion type

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RQ Timestamp="1605141841949">
  <Promotion PromotionType="Customized" PromotionName="Customized Promotion example update" PromotionId="75023474" HotelId="203103755"/>
  <SaleDateRange Start="2021-01-01" End="2021-03-05"/>
  <StayDateRange Start="2021-02-01" End="2021-06-05"/>
  <MinNoOfRooms>2</MinNoOfRooms>
  <BlackoutDateRange>
    <DateRange Start="2021-03-15" End="2021-03-30"/>
    <DateRange Start="2021-06-01" End="2021-06-03"/>
  </BlackoutDateRange>
  <LengthOfStay Min="1" Max="7"/>
  <BookOn>
    <Day>Tuesday</Day>
    <Day>Thursday</Day>
    <Day>Saturday</Day>
  </BookOn>
  <StayOn>
    <Day>Monday</Day>
    <Day>Wednesday</Day>
    <Day>Friday</Day>
  </StayOn>
  <CheckinOn>
    <Day>Wednesday</Day>
    <Day>Thursday</Day>
    <Day>Friday</Day>
    <Day>Saturday</Day>
  </CheckinOn>
  <BookingTime From="12:00" To="22:00"/>
  <IsStackable>false</IsStackable>
  <Discount>
    <PercentPerNight NightType="SpecificDOW">
      <Value>25.0</Value>
      <Value>15.0</Value>
      <Value>0.0</Value>
      <Value>0.0</Value>
      <Value>0.0</Value>
      <Value>0.0</Value>
      <Value>10.0</Value>
    </PercentPerNight>
  </Discount>
  <CancellationPolicy Id="963"/>
  <Channels>
    <Channel Id="1"/>
    <Channel Id="7"/>
  </Channels>
  <CustomerSegments>
    <CustomerSegment Id="0"/>
  </CustomerSegments>
  <RatePlans>
    <RatePlan Id="0"/>
  </RatePlans>
  <Rooms>
    <Room Id="0"/>
  </Rooms>
</HotelPromotion_RQ>

Request for update EarlyBird promotion type

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RQ Timestamp="1605141841949">
  <Promotion PromotionType="EarlyBird" PromotionName="EarlyBird Promotion - New Year 2022 update" PromotionId="75023475" HotelId="203103755"/>
  <EarlyBird MinAdvPurchase="5"/>
  <SaleDateRange Start="2021-01-01" End="2021-03-01"/>
  <StayDateRange Start="2021-12-01" End="2022-01-05"/>
  <MinNoOfRooms>2</MinNoOfRooms>
  <BlackoutDateRange>
    <DateRange Start="2021-12-31" End="2022-01-01"/>
    <DateRange Start="2021-12-25" End="2021-12-26"/>
  </BlackoutDateRange>
  <LengthOfStay Min="1" Max="7"/>
  <BookOn>
    <Day>Sunday</Day>
    <Day>Tuesday</Day>
    <Day>Thursday</Day>
    <Day>Saturday</Day>
  </BookOn>
  <StayOn>
    <Day>Monday</Day>
    <Day>Wednesday</Day>
    <Day>Friday</Day>
  </StayOn>
  <CheckinOn>
    <Day>Wednesday</Day>
    <Day>Thursday</Day>
    <Day>Friday</Day>
    <Day>Saturday</Day>
  </CheckinOn>
  <BookingTime From="12:00" To="22:00"/>
  <IsStackable>false</IsStackable>
  <Discount>
    <AmountPerNight NightType="SpecificNight">
      <Value>100.0</Value>
      <Value>110.0</Value>
      <Value>120.0</Value>
      <Value>0.0</Value>
      <Value>0.0</Value>
      <Value>0.0</Value>
      <Value>115.0</Value>
    </AmountPerNight>
  </Discount>
  <CancellationPolicy Id="963"/>
  <Channels>
    <Channel Id="1"/>
    <Channel Id="7"/>
  </Channels>
  <CustomerSegments>
    <CustomerSegment Id="0"/>
  </CustomerSegments>
  <RatePlans>
    <RatePlan Id="3371503"/>
  </RatePlans>
  <Rooms>
    <Room Id="1201489087"/>
  </Rooms>
</HotelPromotion_RQ>

Request for update ExpressTonight promotion type

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RQ Timestamp="1605141841949">
  <Promotion PromotionType="ExpressTonight" PromotionName="ExpressTonight Promotion update" PromotionId="75023484" HotelId="203103755"/>
  <SaleDateRange Start="2020-11-19" End="2020-11-20"/>
  <StayDateRange Start="2020-11-19" End="2020-11-21"/>
  <MinNoOfRooms>2</MinNoOfRooms>
  <LengthOfStay Min="1" Max="3"/>
  <BookingTime From="12:00" To="22:00"/>
  <IsStackable>false</IsStackable>
  <Discount>
    <ExpressTonight Value="3000.0" ChannelDiscount="true"/>
  </Discount>
  <CancellationPolicy Id="963"/>
  <Channels>
    <Channel Id="1"/>
    <Channel Id="7"/>
  </Channels>
  <CustomerSegments>
    <CustomerSegment Id="0"/>
  </CustomerSegments>
  <RatePlans>
    <RatePlan Id="0"/>
  </RatePlans>
  <Rooms>
    <Room Id="0"/>
  </Rooms>
</HotelPromotion_RQ>

Request for update LastMinute promotion type

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RQ Timestamp="1605141841949">
  <Promotion PromotionType="LastMinute" PromotionName="LastMinute Promotion update" PromotionId="75023476" HotelId="203103755"/>
  <LastMinute MaxAdvPurchase="2"/>
  <SaleDateRange Start="2021-01-01" End="2021-03-05"/>
  <StayDateRange Start="2021-02-01" End="2021-06-05"/>
  <MinNoOfRooms>2</MinNoOfRooms>
  <BlackoutDateRange>
    <DateRange Start="2021-03-15" End="2021-03-30"/>
    <DateRange Start="2021-06-01" End="2021-06-03"/>
  </BlackoutDateRange>
  <LengthOfStay Min="1" Max="5"/>
  <BookOn>
    <Day>Sunday</Day>
    <Day>Tuesday</Day>
    <Day>Thursday</Day>
    <Day>Saturday</Day>
  </BookOn>
  <StayOn>
    <Day>Monday</Day>
    <Day>Wednesday</Day>
    <Day>Friday</Day>
  </StayOn>
  <CheckinOn>
    <Day>Wednesday</Day>
    <Day>Thursday</Day>
    <Day>Friday</Day>
    <Day>Saturday</Day>
  </CheckinOn>
  <BookingTime From="12:00" To="22:00"/>
  <IsStackable>false</IsStackable>
  <Discount>
    <AmountPerBooking Value="1500.0"/>
  </Discount>
  <CancellationPolicy Id="963"/>
  <Channels>
    <Channel Id="1"/>
    <Channel Id="7"/>
  </Channels>
  <CustomerSegments>
    <CustomerSegment Id="0"/>
  </CustomerSegments>
  <RatePlans>
    <RatePlan Id="0"/>
  </RatePlans>
  <Rooms>
    <Room Id="0"/>
  </Rooms>
</HotelPromotion_RQ>

Request for update LongStay promotion type

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RQ Timestamp="1605141841949">
  <Promotion PromotionType="LongStay" PromotionName="LongStay Promotion update" PromotionId="75023478" HotelId="203103755"/>
  <SaleDateRange Start="2021-01-01" End="2021-03-05"/>
  <StayDateRange Start="2021-02-01" End="2021-06-05"/>
  <MinNoOfRooms>2</MinNoOfRooms>
  <BlackoutDateRange>
    <DateRange Start="2021-03-15" End="2021-03-30"/>
    <DateRange Start="2021-06-01" End="2021-06-03"/>
  </BlackoutDateRange>
  <LengthOfStay Min="3" Max="7"/>
  <BookOn>
    <Day>Sunday</Day>
    <Day>Tuesday</Day>
    <Day>Thursday</Day>
    <Day>Saturday</Day>
  </BookOn>
  <StayOn>
    <Day>Monday</Day>
    <Day>Wednesday</Day>
    <Day>Friday</Day>
  </StayOn>
  <CheckinOn>
    <Day>Wednesday</Day>
    <Day>Thursday</Day>
    <Day>Friday</Day>
    <Day>Saturday</Day>
  </CheckinOn>
  <BookingTime From="12:00" To="22:00"/>
  <IsStackable>false</IsStackable>
  <Discount>
    <FreeNights Value="2" IsRecurring="false"/>
  </Discount>
  <CancellationPolicy Id="963"/>
  <Channels>
    <Channel Id="1"/>
    <Channel Id="7"/>
  </Channels>
  <CustomerSegments>
    <CustomerSegment Id="0"/>
  </CustomerSegments>
  <RatePlans>
    <RatePlan Id="0"/>
  </RatePlans>
  <Rooms>
    <Room Id="0"/>
  </Rooms>
</HotelPromotion_RQ>

Request for update SeventyTwoHours promotion type

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RQ Timestamp="1605141841949">
  <Promotion PromotionType="SeventyTwoHours" PromotionName="SeventyTwoHours Promotion update" PromotionId="75023477" HotelId="203103755"/>
  <SaleDateRange Start="2021-01-01" End="2021-03-05"/>
  <StayDateRange Start="2021-02-01" End="2021-06-05"/>
  <MinNoOfRooms>2</MinNoOfRooms>
  <BlackoutDateRange>
    <DateRange Start="2021-03-15" End="2021-03-30"/>
    <DateRange Start="2021-06-01" End="2021-06-03"/>
  </BlackoutDateRange>
  <LengthOfStay Min="1" Max="7"/>
  <BookOn>
    <Day>Sunday</Day>
    <Day>Tuesday</Day>
    <Day>Thursday</Day>
    <Day>Saturday</Day>
  </BookOn>
  <StayOn>
    <Day>Monday</Day>
    <Day>Wednesday</Day>
    <Day>Friday</Day>
  </StayOn>
  <CheckinOn>
    <Day>Wednesday</Day>
    <Day>Thursday</Day>
    <Day>Friday</Day>
    <Day>Saturday</Day>
  </CheckinOn>
  <BookingTime From="12:00" To="22:00"/>
  <IsStackable>false</IsStackable>
  <Discount>
    <AmountPerBooking Value="400.0"/>
  </Discount>
  <CancellationPolicy Id="963"/>
  <Channels>
    <Channel Id="1"/>
    <Channel Id="7"/>
  </Channels>
  <CustomerSegments>
    <CustomerSegment Id="0"/>
  </CustomerSegments>
  <RatePlans>
    <RatePlan Id="0"/>
  </RatePlans>
  <Rooms>
    <Room Id="0"/>
  </Rooms>
</HotelPromotion_RQ>

Request for update SpecialOffer promotion type

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RQ Timestamp="1605141841949">
  <Promotion PromotionType="SpecialOffer" PromotionName="SpecialOffer Promotion update" PromotionId="75023485" HotelId="203103755"/>
  <SaleDateRange Start="2021-01-01" End="2021-03-05"/>
  <StayDateRange Start="2021-02-01" End="2021-06-05"/>
  <MinNoOfRooms>2</MinNoOfRooms>
  <BlackoutDateRange>
    <DateRange Start="2021-03-15" End="2021-03-30"/>
    <DateRange Start="2021-06-01" End="2021-06-03"/>
  </BlackoutDateRange>
  <LengthOfStay Min="1" Max="7"/>
  <BookOn>
    <Day>Sunday</Day>
    <Day>Tuesday</Day>
    <Day>Thursday</Day>
    <Day>Saturday</Day>
  </BookOn>
  <StayOn>
    <Day>Monday</Day>
    <Day>Wednesday</Day>
    <Day>Friday</Day>
  </StayOn>
  <CheckinOn>
    <Day>Wednesday</Day>
    <Day>Thursday</Day>
    <Day>Friday</Day>
    <Day>Saturday</Day>
  </CheckinOn>
  <BookingTime From="12:00" To="22:00"/>
  <IsStackable>false</IsStackable>
  <Discount>
    <AmountPerBooking Value="4500.0"/>
  </Discount>
  <CancellationPolicy Id="963"/>
  <Channels>
    <Channel Id="1"/>
    <Channel Id="7"/>
  </Channels>
  <CustomerSegments>
    <CustomerSegment Id="0"/>
  </CustomerSegments>
  <RatePlans>
    <RatePlan Id="0"/>
  </RatePlans>
  <Rooms>
    <Room Id="0"/>
  </Rooms>
</HotelPromotion_RQ>

4.1.9. Example HTTP response

Response 200

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RS Tuid="000-000-0000" PromotionId=12345>
  <Success/>
</HotelPromotion_RS>

Response 400

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RS>
<Errors>
  <Error Code="321" ShortText="Required field missing" Status="NotProcessed"/>
</Errors>
</HotelPromotion_RS>

Response 401

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RS>
<Errors>
  <Error Code="497" ShortText="Authorization error" Status="NotProcessed"/>
</Errors>
</HotelPromotion_RS>

4.2. Toggle Promotion

POST /cm/promotion/toggle

4.2.1. Description

This section outlines the feature to activate or deactivate a promotion.

4.2.2. Body parameter

HotelPromotionToggle_RQ must be supplied.

Name : body
Flags : required
Type : HotelPromotionToggle_RQ

4.2.3. Responses

HTTP Code	Description	Schema
200	The promotion has been toggled successfully	No Content
204	The promotion has been toggled already	No Content
400	The request content was malformed	No Content
401	The supplier was unauthorized	No Content

HTTP Code

Description

Schema

200

The promotion has been toggled successfully

No Content

204

The promotion has been toggled already

No Content

400

The request content was malformed

No Content

401

The supplier was unauthorized

No Content

4.2.4. Consumes

application/xml

4.2.5. Produces

application/xml

4.2.6. Tags

PromotionToggle

4.2.7. Security

Type	Name
apiKey	apiKey

Type

Name

apiKey

4.2.8. Example HTTP request

Request path

/cm/promotion/toggle

Request body

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotionToggle_RQ HotelId="680674" IsActive="true" PromotionId="750566" Timestamp="1605243776"/>

4.2.9. Example HTTP response

Response 200

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RS Tuid="000-000-0000" PromotionId=12345>
  <Success/>
</HotelPromotion_RS>

Response 204

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RS>
<Errors>
  <Error Code="444" ShortText="The promotion has been toggled already" Status="NotProcessed"/>
</Errors>
</HotelPromotion_RS>

Response 400

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RS>
<Errors>
  <Error Code="321" ShortText="Required field missing" Status="NotProcessed"/>
</Errors>
</HotelPromotion_RS>

Response 401

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotion_RS>
<Errors>
  <Error Code="497" ShortText="Authorization error" Status="NotProcessed"/>
</Errors>
</HotelPromotion_RS>

4.3. Retrieve Promotions

POST /cm/promotion/retrieve

4.3.1. Description

This section outlines the feature to retrieve promotions. Note that only promotion types supported by this API will be returned. Promotion types not supported by this API but supported on the YCS Extranet will not be returned.

4.3.2. Body parameter

HotelPromotionGet_RQ must be supplied.

Name : body
Flags : required
Type : HotelPromotionGet_RQ

4.3.3. Responses

HTTP Code	Description	Schema
200	The promotions have been retrieved successfully	No Content
400	The request content was malformed	No Content
401	The supplier was unauthorized	No Content

HTTP Code

Description

Schema

200

The promotions have been retrieved successfully

No Content

400

The request content was malformed

No Content

401

The supplier was unauthorized

No Content

4.3.4. Consumes

application/xml

4.3.5. Produces

application/xml

4.3.6. Tags

PromotionRetrieve

4.3.7. Security

Type	Name
apiKey	apiKey

Type

Name

apiKey

4.3.8. Example HTTP request

Request path

/cm/promotion/retrieve

Request body

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotionGet_RQ HotelId="680674" IsActive="true" PromotionId="750566" Timestamp="1605243776"/>

4.3.9. Example HTTP response

Response 200

<HotelPromotionGet_RS Tuid="f2512b30-2a53-11eb-9a46-e72138f17e12">
    <HotelPromotion IsActive="true">
        <Promotion PromotionType="Customized" PromotionName="Customized Promotion example"
        PromotionId="75023474" HotelId="203103755"/>
        <SaleDateRange Start="2021-01-01+07:00" End="2021-03-05+07:00"/>
        <StayDateRange Start="2021-02-01+07:00" End="2021-06-05+07:00"/>
        <MinNoOfRooms>2</MinNoOfRooms>
        <BlackoutDateRange>
            <DateRange Start="2021-03-15+07:00" End="2021-03-30+07:00"/>
            <DateRange Start="2021-06-01+07:00" End="2021-06-03+07:00"/>
        </BlackoutDateRange>
        <LengthOfStay Min="1" Max="7"/>
        <BookOn>
            <Day>Tuesday</Day>
            <Day>Thursday</Day>
            <Day>Saturday</Day>
        </BookOn>
        <StayOn>
            <Day>Monday</Day>
            <Day>Wednesday</Day>
            <Day>Friday</Day>
        </StayOn>
        <CheckinOn>
            <Day>Wednesday</Day>
            <Day>Thursday</Day>
            <Day>Friday</Day>
            <Day>Saturday</Day>
        </CheckinOn>
        <BookingTime To="22:00:00" From="12:00:00"/>
        <IsStackable>false</IsStackable>
        <Discount>
            <PercentPerNight NightType="SpecificDOW">
                <Value>25.0</Value>
                <Value>15.0</Value>
                <Value>0.0</Value>
                <Value>0.0</Value>
                <Value>0.0</Value>
                <Value>0.0</Value>
                <Value>0.0</Value>
            </PercentPerNight>
        </Discount>
        <CancellationPolicy Id="963"/>
        <Channels>
            <Channel Id="1"/>
            <Channel Id="7"/>
        </Channels>
        <CustomerSegments>
            <CustomerSegment Id="0"/>
        </CustomerSegments>
        <RatePlans>
            <RatePlan Id="3371504"/>
        </RatePlans>
        <Rooms>
            <Room Id="1201489087"/>
        </Rooms>
        <PromotionPerformance Revenue="5000.0" NightsAvgPerBooking="3" Bookings="332"/>
    </HotelPromotion>
</HotelPromotionGet_RS>

Response 400

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotionGet_RS>
<Errors>
  <Error Code="321" ShortText="Required field missing" Status="NotProcessed"/>
</Errors>
</HotelPromotionGet_RS>

Response 401

<?xml version="1.0" encoding="UTF-8"?>
<HotelPromotionGet_RS>
<Errors>
  <Error Code="497" ShortText="Authorization error" Status="NotProcessed"/>
</Errors>
</HotelPromotionGet_RS>

4.4. Get Error Codes

GET /cm/codes/promotion/error-codes

4.4.1. Description

Get list of all Promotion API error codes

4.4.2. Responses

HTTP Code	Description	Schema
200	Success	ErrorCodes
500	Internal server error	ErrorResponse

HTTP Code

Description

Schema

200

Success

ErrorCodes

500

Internal server error

ErrorResponse

4.4.3. Consumes

application/xml

4.4.4. Produces

application/xml

4.4.5. Tags

ErrorCodes

4.4.6. Example HTTP request

Request path

/cm/codes/promotion/error-codes

4.4.7. Example HTTP response

Response 200

<?xml version="1.0" encoding="UTF-8"?>
<ErrorCodes>
  <ErrorCode Code="321" Description="Required field missing"/>
</ErrorCodes>

Response 500

<?xml version="1.0" encoding="UTF-8"?>
<ErrorResponse CorrelationID="8b417d6a-f3df-4d65-870c-240378b8ad3e" Endpoint="RoomAmenities">
  <Errors>
    <Error Code="321" ShortText="Required field missing" Status="NotProcessed"/>
  </Errors>
  <Warnings>
    <Warning Code="123" ShortText="Please try again in a few minutes" Status="Incomplete"/>
  </Warnings>
</ErrorResponse>

5. Definitions

5.1. AmountPerBooking

Name Description Schema

Name	Description	Schema
@Value required	Discount amount per booking value. (Between 0.0 - 99999999.0) Example : `350.0`	number (double)

@Value
required

Discount amount per booking value. (Between 0.0 - 99999999.0)
Example : 350.0

number (double)

5.2. AmountPerNight

Name Description Schema

Name	Description	Schema
@NightType required	Required one of night types as follows: EveryNight, SpecificNight, SpecificDOW, FirstNight, and LastNight. Example : `"EveryNight"`	enum (EVERY_NIGHT, SPECIFIC_NIGHT, SPECIFIC_DOW, FIRST_NIGHT, LAST_NIGHT)
Value required	List of discount amount per night value. (Between 0.0 - 99999999.0) Example : `"[350.0]"`	< number (double) > array

@NightType
required

Required one of night types as follows: EveryNight, SpecificNight, SpecificDOW, FirstNight, and LastNight.
Example : "EveryNight"

enum (EVERY_NIGHT, SPECIFIC_NIGHT, SPECIFIC_DOW, FIRST_NIGHT, LAST_NIGHT)

Value
required

List of discount amount per night value. (Between 0.0 - 99999999.0)
Example : "[350.0]"

< number (double) > array

5.3. CancellationPolicy

Name Description Schema

Name	Description	Schema
@Id required	Cancellation policy ID See: Get a list of supported cancel policies Example : `0`	integer (int32)

@Id
required

Cancellation policy ID

See: Get a list of supported cancel policies
Example : 0

integer (int32)

5.4. ChannelType

Name Description Schema

Name	Description	Schema
@Id required	Channel ID See: Get list of supported channels Example : `0`	integer (int64)

@Id
required

Channel ID

See: Get list of supported channels
Example : 0

integer (int64)

5.5. Channels

Name Description Schema

Name	Description	Schema
Channel required	Channel of a promotion. This specifies that this channel is applicable to the promotion. Example : `[ "ChannelType" ]`	< ChannelType > array

Channel
required

Channel of a promotion. This specifies that this channel is applicable to the promotion.
Example : [ "ChannelType" ]

< ChannelType > array

5.6. CustomerSegmentType

Name Description Schema

Name	Description	Schema
@Id required	Customer Segment Group ID See: Get a list of supported Customer Segment Groups Example : `0`	integer (int64)

@Id
required

Customer Segment Group ID

See: Get a list of supported Customer Segment Groups
Example : 0

integer (int64)

5.7. CustomerSegments

Name Description Schema

Name	Description	Schema
CustomerSegment required	Customer segment of a promotion. This specifies that this customer segment is applicable to the promotion. Example : `[ "CustomerSegmentType" ]`	< CustomerSegmentType > array

CustomerSegment
required

Customer segment of a promotion. This specifies that this customer segment is applicable to the promotion.
Example : [ "CustomerSegmentType" ]

< CustomerSegmentType > array

5.8. DateRange

Name Description Schema

Name	Description	Schema
DateRange optional	This encloses one or more date ranges. Example : `[ "DateRangeMandatory" ]`	< DateRangeMandatory > array

DateRange
optional

This encloses one or more date ranges.
Example : [ "DateRangeMandatory" ]

< DateRangeMandatory > array

5.9. DateRangeMandatory

Name Description Schema

Name	Description	Schema
@End required	End datetime. Example : `"1970-01-01"`	string (date-time)
@Start required	Start datetime. Example : `"1970-01-01"`	string (date-time)

@End
required

End datetime.
Example : "1970-01-01"

string (date-time)

@Start
required

Start datetime.
Example : "1970-01-01"

string (date-time)

5.10. DateRangeType

Name Description Schema

Name	Description	Schema
@End optional	End datetime. If not passed, there will not be an end date. Example : `"1970-01-01"`	string (date-time)
@Start required	Start datetime. Example : `"1970-01-01"`	string (date-time)

@End
optional

End datetime. If not passed, there will not be an end date.
Example : "1970-01-01"

string (date-time)

@Start
required

Start datetime.
Example : "1970-01-01"

string (date-time)

5.11. DayType

Name Description Schema

Name	Description	Schema
Day optional	Day of the week Example : `"Monday"`	< string > array

Day
optional

Day of the week
Example : "Monday"

< string > array

5.12. Discount

Name	Description	Schema
AmountPerBooking optional	AmountPerBooking discount type. Example : AmountPerBooking	AmountPerBooking
AmountPerNight optional	AmountPerNight discount type. Example : AmountPerNight	AmountPerNight
ExpressTonight optional	ExpressTonight discount type. Example : ExpressTonight	ExpressTonight
FreeNights optional	FreeNights discount type. Example : FreeNights	FreeNights
PercentPerNight optional	PercentPerNight discount type. Example : PercentPerNight	PercentPerNight

Name

Description

Schema

AmountPerBooking
optional

AmountPerBooking discount type.
Example : AmountPerBooking

AmountPerBooking

AmountPerNight
optional

AmountPerNight discount type.
Example : AmountPerNight

AmountPerNight

ExpressTonight
optional

ExpressTonight discount type.
Example : ExpressTonight

ExpressTonight

FreeNights
optional

FreeNights discount type.
Example : FreeNights

FreeNights

PercentPerNight
optional

PercentPerNight discount type.
Example : PercentPerNight

PercentPerNight

5.13. EarlyBird

Name Description Schema

Name	Description	Schema
@MinAdvPurchase required	Minimum advance purchase day. Minimum value : `0` Maximum value : `365` Example : `0`	integer (int32)

@MinAdvPurchase
required

Minimum advance purchase day.
Minimum value : 0
Maximum value : 365
Example : 0

integer (int32)

5.14. ErrorCode

Name Description Schema

Name	Description	Schema
@Code required	Code of an Agoda error message. Example : `321`	integer (int32)
@Description required	Description of an Agoda error message. Example : `"Required field missing"`	string

@Code
required

Code of an Agoda error message.
Example : 321

integer (int32)

@Description
required

Description of an Agoda error message.
Example : "Required field missing"

string

5.15. ErrorCodes

Name Description Schema

Name	Description	Schema
ErrorCode required	List of error codes Example : `[ "ErrorCode" ]`	< ErrorCode > array

ErrorCode
required

List of error codes
Example : [ "ErrorCode" ]

< ErrorCode > array

5.16. ErrorResponse

Name Description Schema

Name	Description	Schema
@CorrelationID required	Allows end-to-end correlation of log messages with the corresponding Web service message throughout the processing of the Web service message. Example : `"8b417d6a-f3df-4d65-870c-240378b8ad3e"`	string
@Endpoint required	Endpoint name Example : `"RoomAmenities"`	string
Errors required	A collection of errors that occurred during the processing of a message. Example : ErrorsType	ErrorsType
Warnings required	A collection of warnings that occurred during the processing of a message. Example : WarningsType	WarningsType

@CorrelationID
required

Allows end-to-end correlation of log messages with the corresponding Web service message throughout the processing of the Web service message.
Example : "8b417d6a-f3df-4d65-870c-240378b8ad3e"

string

@Endpoint
required

Endpoint name
Example : "RoomAmenities"

string

Errors
required

A collection of errors that occurred during the processing of a message.
Example : ErrorsType

ErrorsType

Warnings
required

A collection of warnings that occurred during the processing of a message.
Example : WarningsType

WarningsType

5.17. ErrorType

Name Description Schema

Name	Description	Schema
@Code required	This refers to a table of coded values exchanged between applications to identify errors or warnings. Refer to OpenTravel Code List Error Codes (ERR). Example : `"321"`	string
@ShortText required	An abbreviated version of the error in textual format. Example : `"Required field missing"`	string
@Status required	Recommended values are those enumerated in the OTA_ErrorRS, (NotProcessed \| Incomplete \| Complete \| Unknown) however, the data type is designated as string data, recognizing that trading partners may identify additional status conditions not included in the enumeration. Example : `"NotProcessed"`	string

@Code
required

This refers to a table of coded values exchanged between applications to identify errors or warnings. Refer to OpenTravel Code List Error Codes (ERR).
Example : "321"

string

@ShortText
required

An abbreviated version of the error in textual format.
Example : "Required field missing"

string

@Status
required

Recommended values are those enumerated in the OTA_ErrorRS, (NotProcessed | Incomplete | Complete | Unknown) however, the data type is designated as string data, recognizing that trading partners may identify additional status conditions not included in the enumeration.
Example : "NotProcessed"

string

5.18. ErrorsType

Name Description Schema

Name	Description	Schema
Error required	An error that occurred during the processing of a message. Example : `[ "ErrorType" ]`	< ErrorType > array

Error
required

An error that occurred during the processing of a message.
Example : [ "ErrorType" ]

< ErrorType > array

5.19. ExpressTonight

Name Description Schema

Name	Description	Schema
@ChannelDiscount optional	ChannelDiscount flag. Example : `true`	boolean
@Value required	Amount of ExpressTonight discount type value. (Between 0.0 - 99999999.0) Example : `350.0`	number (double)

@ChannelDiscount
optional

ChannelDiscount flag.
Example : true

boolean

@Value
required

Amount of ExpressTonight discount type value. (Between 0.0 - 99999999.0)
Example : 350.0

number (double)

5.20. FreeNights

Name Description Schema

Name	Description	Schema
@IsRecurring required	IsRecurring flag. Example : `true`	boolean
@Value required	Free nights value. Example : `1`	integer (int32)

@IsRecurring
required

IsRecurring flag.
Example : true

boolean

@Value
required

Free nights value.
Example : 1

integer (int32)

5.21. HotelPromotion

Name Description Schema

Name	Description	Schema
@IsActive required	Active Status of a promotion. Example : `true`	boolean
BlackoutDateRange optional	Blackout date ranges of a promotion. Example : DateRange	DateRange
BookOn optional	Book on days of week condition of a promotion. The day will be applicable if included. By default, every day of the week is applicable. Example : DayType	DayType
BookingTime optional	Booking time range condition of a promotion. Example : TimeRangeType	TimeRangeType
CancellationPolicy required	Cancellation policy of a promotion. Example : CancellationPolicy	CancellationPolicy
Channels optional	Channels of a promotion. By default, the promotion will be applied to all channels. Example : Channels	Channels
CheckinOn optional	Check-in on days of week condition of a promotion. The day will be applicable if included. By default, every day of the week is applicable. Example : DayType	DayType
CustomerSegments optional	CustomerSegments of a promotion. By default, the promotion will be applied to all customer segments. Example : CustomerSegments	CustomerSegments
Discount required	Discount detail of a promotion. (required one of discount type as follows: AmountPerBooking, AmountPerNight, PercentPerNight, FreeNights, and ExpressTonight) Example : Discount	Discount
EarlyBird optional	For EarlyBird promotion type only. Example : EarlyBird	EarlyBird
IsStackable optional	This specifies if this promotion can be combined with other active promotions. (e.g., if you have an existing active promotion of 20% and load this promotion for 10%, the total discount will be 30%). It will also combine with existing active stackable promotions. Default : `false` Example : `true`	boolean
LastMinute optional	For LastMinute promotion type only. Example : LastMinute	LastMinute
LengthOfStay optional	Length of stay condition of a promotion. Example : RangeType	RangeType
MinNoOfRooms optional	Minimum number of rooms condition of a promotion. (between 1 - 5) Example : `1`	integer (int32)
Promotion required	Promotion of a hotel. Example : Promotion	Promotion
PromotionPerformance required	Promotion’s Performance. Example : PromotionPerformance	PromotionPerformance
RatePlans optional	RatePlans of a promotion. By default, the promotion will be applied to all rate plans. Example : RatePlans	RatePlans
RoomIds optional	Rooms of a promotion. This specifies that the Agoda Rooms are applicable to the promotion. By default, the promotion will be applied to all rooms. Example : Rooms	Rooms
SaleDateRange required	Range of promotion’s sale dates. Example : DateRangeType	DateRangeType
StayDateRange required	Range of promotion’s stay dates. Example : DateRangeType	DateRangeType
StayOn optional	Stay on days of week condition of a promotion. The day will be applicable if included. By default, every day of the week is applicable. Example : DayType	DayType

@IsActive
required

Active Status of a promotion.
Example : true

boolean

BlackoutDateRange
optional

Blackout date ranges of a promotion.
Example : DateRange

DateRange

BookOn
optional

Book on days of week condition of a promotion. The day will be applicable if included. By default, every day of the week is applicable.
Example : DayType

DayType

BookingTime
optional

Booking time range condition of a promotion.
Example : TimeRangeType

TimeRangeType

CancellationPolicy
required

Cancellation policy of a promotion.
Example : CancellationPolicy

CancellationPolicy

Channels
optional

Channels of a promotion. By default, the promotion will be applied to all channels.
Example : Channels

Channels

CheckinOn
optional

Check-in on days of week condition of a promotion. The day will be applicable if included. By default, every day of the week is applicable.
Example : DayType

DayType

CustomerSegments
optional

CustomerSegments of a promotion. By default, the promotion will be applied to all customer segments.
Example : CustomerSegments

CustomerSegments

Discount
required

Discount detail of a promotion. (required one of discount type as follows: AmountPerBooking, AmountPerNight, PercentPerNight, FreeNights, and ExpressTonight)
Example : Discount

Discount

EarlyBird
optional

For EarlyBird promotion type only.
Example : EarlyBird

EarlyBird

IsStackable
optional

This specifies if this promotion can be combined with other active promotions. (e.g., if you have an existing active promotion of 20% and load this promotion for 10%, the total discount will be 30%). It will also combine with existing active stackable promotions.
Default : false
Example : true

boolean

LastMinute
optional

For LastMinute promotion type only.
Example : LastMinute

LastMinute

LengthOfStay
optional

Length of stay condition of a promotion.
Example : RangeType

RangeType

MinNoOfRooms
optional

Minimum number of rooms condition of a promotion. (between 1 - 5)
Example : 1

integer (int32)

Promotion
required

Promotion of a hotel.
Example : Promotion

Promotion

PromotionPerformance
required

Promotion’s Performance.
Example : PromotionPerformance

PromotionPerformance

RatePlans
optional

RatePlans of a promotion. By default, the promotion will be applied to all rate plans.
Example : RatePlans

RatePlans

RoomIds
optional

Rooms of a promotion. This specifies that the Agoda Rooms are applicable to the promotion. By default, the promotion will be applied to all rooms.
Example : Rooms

Rooms

SaleDateRange
required

Range of promotion’s sale dates.
Example : DateRangeType

DateRangeType

StayDateRange
required

Range of promotion’s stay dates.
Example : DateRangeType

DateRangeType

StayOn
optional

Stay on days of week condition of a promotion. The day will be applicable if included. By default, every day of the week is applicable.
Example : DayType

DayType

5.22. HotelPromotionGet_RQ

Name Description Schema

Name	Description	Schema
@HotelId required	Hotel ID of Promotions. Example : `680674`	integer (int32)
@IsActive optional	Active status of a promotion. Example : `true`	boolean
@PromotionId optional	Promotion’s ID. Example : `750566`	integer (int64)
@Timestamp required	Request unix timestamp Example : `1605243776`	integer (int64)

@HotelId
required

Hotel ID of Promotions.
Example : 680674

integer (int32)

@IsActive
optional

Active status of a promotion.
Example : true

boolean

@PromotionId
optional

Promotion’s ID.
Example : 750566

integer (int64)

@Timestamp
required

Request unix timestamp
Example : 1605243776

integer (int64)

5.23. HotelPromotionGet_RS

Name Description Schema

Name	Description	Schema
@Tuid optional	TUID of a promotion. Example : `"string"`	string
Errors optional	A collection of errors that occurred during the processing of a message. Example : ErrorsType	ErrorsType
HotelPromotion optional	Promotions of a hotel. Example : `[ "HotelPromotion" ]`	< HotelPromotion > array
Success optional	Returning an empty element of this type indicates the successful processing of a message. Example : SuccessType	SuccessType

@Tuid
optional

TUID of a promotion.
Example : "string"

string

Errors
optional

A collection of errors that occurred during the processing of a message.
Example : ErrorsType

ErrorsType

HotelPromotion
optional

Promotions of a hotel.
Example : [ "HotelPromotion" ]

< HotelPromotion > array

Success
optional

Returning an empty element of this type indicates the successful processing of a message.
Example : SuccessType

SuccessType

5.24. HotelPromotionToggle_RQ

Name Description Schema

Name	Description	Schema
@HotelId required	Hotel ID of Promotions. Example : `680674`	integer (int32)
@IsActive required	Active Status of a promotion. Example : `true`	boolean
@PromotionId required	Promotion’s ID. Example : `750566`	integer (int64)
@Timestamp required	Request unix timestamp Example : `1605243776`	integer (int64)

@HotelId
required

Hotel ID of Promotions.
Example : 680674

integer (int32)

@IsActive
required

Active Status of a promotion.
Example : true

boolean

@PromotionId
required

Promotion’s ID.
Example : 750566

integer (int64)

@Timestamp
required

Request unix timestamp
Example : 1605243776

integer (int64)

5.25. HotelPromotionToggle_RS

Name Description Schema

Name	Description	Schema
@PromotionId optional	ID of toggled promotion. Example : `2762320`	integer (int32)
@Tuid optional	TUID of toggled promotion. Example : `"string"`	string
Errors optional	A collection of errors that occurred during the processing of a message. Example : ErrorsType	ErrorsType
Success optional	Returning an empty element of this type indicates the successful processing of a message. Example : SuccessType	SuccessType

@PromotionId
optional

ID of toggled promotion.
Example : 2762320

integer (int32)

@Tuid
optional

TUID of toggled promotion.
Example : "string"

string

Errors
optional

A collection of errors that occurred during the processing of a message.
Example : ErrorsType

ErrorsType

Success
optional

Returning an empty element of this type indicates the successful processing of a message.
Example : SuccessType

SuccessType

5.26. HotelPromotion_RQ

Name Description Schema

Name	Description	Schema
@Timestamp required	Request unix timestamp Example : `1605243776`	integer (int64)
BlackoutDateRange optional	Blackout date ranges of a promotion. Example : DateRange	DateRange
BookOn optional	Book on days of week condition of a promotion. The day will be applicable if included. By default, every day of the week is applicable. Example : DayType	DayType
BookingTime optional	Booking time range condition of a promotion. Example : TimeRangeType	TimeRangeType
CancellationPolicy required	Cancellation policy of a promotion. Example : CancellationPolicy	CancellationPolicy
Channels optional	Channels of a promotion. By default, the promotion will be applied to all channels. Example : Channels	Channels
CheckinOn optional	Check-in on days of week condition of a promotion. The day will be applicable if included. By default, every day of the week is applicable. Example : DayType	DayType
CustomerSegments optional	CustomerSegments of a promotion. By default, the promotion will be applied to all customer segments. Example : CustomerSegments	CustomerSegments
Discount required	Discount detail of a promotion. (required one of discount type as follows: AmountPerBooking, AmountPerNight, PercentPerNight, FreeNights, and ExpressTonight) Example : Discount	Discount
EarlyBird optional	Required for EarlyBird promotion type only. Example : EarlyBird	EarlyBird
IsStackable optional	This specifies if this promotion can be combined with other active promotions. (e.g., if you have an existing active promotion of 20% and load this promotion for 10%, the total discount will be 30%). It will also combine with existing active stackable promotions. (not applicable for Express Tonight Promotion) Default : `false` Example : `true`	boolean
LastMinute optional	Required for LastMinute promotion type only. Example : LastMinute	LastMinute
LengthOfStay optional	Length of stay condition of a promotion. Example : RangeType	RangeType
MinNoOfRooms optional	Minimum number of rooms condition of a promotion. (between 1 - 5) Example : `1`	integer (int32)
Promotion required	Promotion of a hotel. Example : Promotion	Promotion
RatePlans optional	RatePlans of a promotion. By default, the promotion will be applied to all rate plans. Example : RatePlans	RatePlans
RoomIds optional	Rooms of a promotion. This specifies that the Agoda Rooms are applicable to the promotion. By default, the promotion will be applied to all rooms. Example : Rooms	Rooms
SaleDateRange required	Range of promotion’s sale dates. Example : DateRangeType	DateRangeType
StayDateRange required	Range of promotion’s stay dates. Example : DateRangeType	DateRangeType
StayOn optional	Stay on days of week condition of a promotion. The day will be applicable if included. By default, every day of the week is applicable. Example : DayType	DayType

@Timestamp
required

Request unix timestamp
Example : 1605243776

integer (int64)

BlackoutDateRange
optional

Blackout date ranges of a promotion.
Example : DateRange

DateRange

BookOn
optional

Book on days of week condition of a promotion. The day will be applicable if included. By default, every day of the week is applicable.
Example : DayType

DayType

BookingTime
optional

Booking time range condition of a promotion.
Example : TimeRangeType

TimeRangeType

CancellationPolicy
required

Cancellation policy of a promotion.
Example : CancellationPolicy

CancellationPolicy

Channels
optional

Channels of a promotion. By default, the promotion will be applied to all channels.
Example : Channels

Channels

CheckinOn
optional

Check-in on days of week condition of a promotion. The day will be applicable if included. By default, every day of the week is applicable.
Example : DayType

DayType

CustomerSegments
optional

CustomerSegments of a promotion. By default, the promotion will be applied to all customer segments.
Example : CustomerSegments

CustomerSegments

Discount
required

Discount detail of a promotion. (required one of discount type as follows: AmountPerBooking, AmountPerNight, PercentPerNight, FreeNights, and ExpressTonight)
Example : Discount

Discount

EarlyBird
optional

Required for EarlyBird promotion type only.
Example : EarlyBird

EarlyBird

IsStackable
optional

boolean

LastMinute
optional

Required for LastMinute promotion type only.
Example : LastMinute

LastMinute

LengthOfStay
optional

Length of stay condition of a promotion.
Example : RangeType

RangeType

MinNoOfRooms
optional

Minimum number of rooms condition of a promotion. (between 1 - 5)
Example : 1

integer (int32)

Promotion
required

Promotion of a hotel.
Example : Promotion

Promotion

RatePlans
optional

RatePlans of a promotion. By default, the promotion will be applied to all rate plans.
Example : RatePlans

RatePlans

RoomIds
optional

Rooms of a promotion. This specifies that the Agoda Rooms are applicable to the promotion. By default, the promotion will be applied to all rooms.
Example : Rooms

Rooms

SaleDateRange
required

Range of promotion’s sale dates.
Example : DateRangeType

DateRangeType

StayDateRange
required

Range of promotion’s stay dates.
Example : DateRangeType

DateRangeType

StayOn
optional

Stay on days of week condition of a promotion. The day will be applicable if included. By default, every day of the week is applicable.
Example : DayType

DayType

5.27. HotelPromotion_RS

Name Description Schema

Name	Description	Schema
@PromotionId optional	ID of created/updated promotion. Example : `2434021`	integer (int32)
@Tuid optional	TUID of created/updated promotion. Example : `"string"`	string
Errors optional	A collection of errors that occurred during the processing of a message. Example : ErrorsType	ErrorsType
Success optional	Returning an empty element of this type indicates the successful processing of a message. Example : SuccessType	SuccessType

@PromotionId
optional

ID of created/updated promotion.
Example : 2434021

integer (int32)

@Tuid
optional

TUID of created/updated promotion.
Example : "string"

string

Errors
optional

A collection of errors that occurred during the processing of a message.
Example : ErrorsType

ErrorsType

Success
optional

Returning an empty element of this type indicates the successful processing of a message.
Example : SuccessType

SuccessType

5.28. LastMinute

Name Description Schema

Name	Description	Schema
@MaxAdvPurchase optional	Maximum advance purchase day. Minimum value : `0` Maximum value : `365` Example : `180`	integer (int32)

@MaxAdvPurchase
optional

Maximum advance purchase day.
Minimum value : 0
Maximum value : 365
Example : 180

integer (int32)

5.29. PercentPerNight

Name Description Schema

Name	Description	Schema
@NightType required	Required one of night types as follows: EveryNight, SpecificNight, SpecificDOW, FirstNight, and LastNight. Example : `"EVERY_NIGHT"`	enum (EVERY_NIGHT, SPECIFIC_NIGHT, SPECIFIC_DOW, FIRST_NIGHT, LAST_NIGHT)
Value required	List of percent per night value. (Between 0.0 - 90.0) Example : `[ 0.0 ]`	< number (double) > array

@NightType
required

Required one of night types as follows: EveryNight, SpecificNight, SpecificDOW, FirstNight, and LastNight.
Example : "EVERY_NIGHT"

enum (EVERY_NIGHT, SPECIFIC_NIGHT, SPECIFIC_DOW, FIRST_NIGHT, LAST_NIGHT)

Value
required

List of percent per night value. (Between 0.0 - 90.0)
Example : [ 0.0 ]

< number (double) > array

5.30. Promotion

Name Description Schema

Name	Description	Schema
@HotelId required	Hotel’s ID. Example : `989173`	integer (int32)
@PromotionExternalId optional	Promotion’s external ID. Example : `"EXTPROMO-001"`	string
@PromotionId optional	Internal Agoda promotion’s ID. (required for update only) Example : `672301`	integer (int32)
@PromotionName optional	Promotion’s name. Example : `"11.11 mega sale promotion."`	string
@PromotionType required	Promotion’s type. (required one of promotion types as follows: Customized, EarlyBird, LastMinute, SeventyTwoHours, ExpressTonight, LongStay, and SpecialOffer) Example : `"EarlyBird"`	enum (CUSTOMIZED, EARLY_BIRD, LAST_MINUTE, SEVENTY_TWO_HOURS, EXPRESS_TONIGHT, LONG_STAY, SPECIAL_OFFER)

@HotelId
required

Hotel’s ID.
Example : 989173

integer (int32)

@PromotionExternalId
optional

Promotion’s external ID.
Example : "EXTPROMO-001"

string

@PromotionId
optional

Internal Agoda promotion’s ID. (required for update only)
Example : 672301

integer (int32)

@PromotionName
optional

Promotion’s name.
Example : "11.11 mega sale promotion."

string

@PromotionType
required

Promotion’s type. (required one of promotion types as follows: Customized, EarlyBird, LastMinute, SeventyTwoHours, ExpressTonight, LongStay, and SpecialOffer)
Example : "EarlyBird"

enum (CUSTOMIZED, EARLY_BIRD, LAST_MINUTE, SEVENTY_TWO_HOURS, EXPRESS_TONIGHT, LONG_STAY, SPECIAL_OFFER)

5.31. PromotionPerformance

Name Description Schema

Name	Description	Schema
@Bookings optional	Number of bookings via this promotion. Example : `999`	integer (int32)
@NightsAvgPerBooking optional	Nights average per booking of this promotion. Example : `3`	integer (int32)
@Revenue optional	Revenue of this promotion. Example : `10000.0`	number (double)

@Bookings
optional

Number of bookings via this promotion.
Example : 999

integer (int32)

@NightsAvgPerBooking
optional

Nights average per booking of this promotion.
Example : 3

integer (int32)

@Revenue
optional

Revenue of this promotion.
Example : 10000.0

number (double)

5.32. RangeType

Name Description Schema

Name	Description	Schema
@Max optional	Maximum value. Example : `30`	integer (int32)
@Min optional	Minimum value. Example : `1`	integer (int32)

@Max
optional

Maximum value.
Example : 30

integer (int32)

@Min
optional

Minimum value.
Example : 1

integer (int32)

5.33. RatePlanType

Name Description Schema

Name	Description	Schema
@Id required	Rate Plan ID See: Get list of rate plans Example : `0`	integer (int64)

@Id
required

Rate Plan ID

See: Get list of rate plans
Example : 0

integer (int64)

5.34. RatePlans

Name Description Schema

Name	Description	Schema
RatePlan required	Rate plan of a promotion. This specifies that this rate plan is applicable to the promotion. Example : `[ "RatePlanType" ]`	< RatePlanType > array

RatePlan
required

Rate plan of a promotion. This specifies that this rate plan is applicable to the promotion.
Example : [ "RatePlanType" ]

< RatePlanType > array

5.35. RoomType

Name Description Schema

Name	Description	Schema
@Id required	Room ID See: Get list of rooms Example : `0`	integer (int64)

@Id
required

Room ID

See: Get list of rooms
Example : 0

integer (int64)

5.36. Rooms

Name Description Schema

Name	Description	Schema
Room required	Room of a promotion. This specifies that this room is applicable to the promotion. Example : `[ "RoomType" ]`	< RoomType > array

Room
required

Room of a promotion. This specifies that this room is applicable to the promotion.
Example : [ "RoomType" ]

< RoomType > array

5.37. SuccessType

Type : object

5.38. TimeRangeType

Name Description Schema

Name	Description	Schema
@From optional	Time from. Example : `"12:00"`	string
@To optional	Time to. Example : `"22:00"`	string

@From
optional

Time from.
Example : "12:00"

string

@To
optional

Time to.
Example : "22:00"

string

5.39. WarningType

Name Description Schema

Name	Description	Schema
@Code required	This refers to a table of coded values exchanged between applications to identify errors or warnings. Refer to OpenTravel Code List Error Codes (ERR). Example : `"123"`	string
@ShortText required	An abbreviated version of the warning in textual format. Example : `"Please try again in a few minutes"`	string
@Status required	Recommended values are those enumerated in the OTA_ErrorRS, (NotProcessed \| Incomplete \| Complete \| Unknown) however, the data type is designated as string data, recognizing that trading partners may identify additional status conditions not included in the enumeration. Example : `"Incomplete"`	string

@Code
required

This refers to a table of coded values exchanged between applications to identify errors or warnings. Refer to OpenTravel Code List Error Codes (ERR).
Example : "123"

string

@ShortText
required

An abbreviated version of the warning in textual format.
Example : "Please try again in a few minutes"

string

@Status
required

string

5.40. WarningsType

Name Description Schema

Name	Description	Schema
Warning required	Optionally used to indicate that the recipient of the request message identified one or more business-level warnings. Example : `[ "WarningType" ]`	< WarningType > array

Warning
required

Optionally used to indicate that the recipient of the request message identified one or more business-level warnings.
Example : [ "WarningType" ]

< WarningType > array

6. FAQ

6.1. When updating a promotion and optional fields are not passed, will they get deleted?

All fields that not passed with request will assign with default value. Suggest to include all fields with request.

6.2. Are the date and time fields based on hotel time zone?

Yes.

6.3. How do we specify the discounts with different NightType ?

For SpecificNight, suggest to provide 7 values, starting with the discounted value for the first night till the seventh night. (if provide less than 7 values then the rest will fill with default value: 0.0 / provide more than 7 values is not allowed)
      <AmountPerNight NightType="SpecificNight">
         <Value>0.0</Value>
         <Value>110.0</Value>
         <Value>110.0</Value>
         <Value>120.0</Value>
         <Value>0.0</Value>
         <Value>130.0</Value>
         <Value>130.0</Value>
      </AmountPerNight>

For SpecificDOW, suggest to provide 7 values, starting with the discounted percentage for Sunday till Saturday. (if provide less than 7 values then the rest will fill with default value: 0.0 / provide more than 7 values is not allowed)
      <PercentPerNight NightType="SpecificDOW">
         <Value>25.0</Value>
         <Value>20.0</Value>
         <Value>0.0</Value>
         <Value>25.0</Value>
         <Value>10.0</Value>
         <Value>0.0</Value>
         <Value>0.0</Value>
      </PercentPerNight>

For EveryNight, suggest to provide only 1 value. (will ignore the rest if provide more than 1)
    <AmountPerNight NightType="EveryNight">
         <Value>110.0</Value>
      </AmountPerNight>

For FirstNight, suggest to provide only 1 value. (will ignore the rest if provide more than 1)
    <PercentPerNight NightType="FirstNight">
         <Value>110.0</Value>
      </PercentPerNight>

For LastNight, suggest to provide only 1 value. (will ignore the rest if provide more than 1)
    <AmountPerNight NightType="LastNight">
         <Value>110.0</Value>
      </AmountPerNight>