Skip to content
Wink

Update a promotion

PUT
/api/managing-entity/{managingEntityIdentifier}/extranet/promotion/{rateModifierIdentifier}
curl --request PUT \
  --url https://api.wink.travel/api/managing-entity/d5b8a3c2-9e6f-4a1b-8d34-7c2e1f0a5b69/extranet/promotion/550e8400-e29b-41d4-a716-446655440000 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Wink-Version: 2.0' \
  --data null

Modify an existing promotion’s name, rules, and qualification criteria.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
managingEntityIdentifier
required
string format: uuid
""

The unique identifier of the managing entity (property).

Example
d5b8a3c2-9e6f-4a1b-8d34-7c2e1f0a5b69
rateModifierIdentifier
required
string format: uuid
""

The unique identifier of the promotion to update.

Example
550e8400-e29b-41d4-a716-446655440000

Header Parameters

Section titled “Header Parameters”
Wink-Version
string
default: 2.0.0
Allowed values: 2.0

Request Bodyrequired

Section titled “Request Bodyrequired”

Updated promotion definition with revised name, discount or premium rules, or qualification criteria

Media typeapplication/json

Request payload for creating or updating a special rate promotion with all its qualifying conditions.

object
addOnIdentifiers

Optional: apply promotion only to specific add-ons or upgrades.

Array<string>
advanceBookingRateQualifier

Optional: restrict promotion to bookings made in advance (minimum days before stay).

object
maxAdvanceBookingOffset

Maximum days in advance of stay start date when the booking may be made. Set to 0 for no maximum.

integer format: int32
""
Example
365
minAdvanceBookingOffset

Minimum days in advance of stay start date when the booking must be made. Set to 0 for no minimum.

integer format: int32
""
Example
7
Example
{
  "maxAdvanceBookingOffset": 365,
  "minAdvanceBookingOffset": 7
}
arrivalDaysOfWeekRateQualifier

Optional: restrict promotion to guests arriving on specific days of the week.

object
daysOfWeek
required

The days of the week when this rate is available for guests to arrive on

object
disabled

Convenience property to quickly determine if this existing object has any active days enabled.

boolean
Example
true
fri

Set to true to enable Friday.

boolean
Example
true
mon

Set to true to enable Monday.

boolean
Example
true
sat

Set to true to enable Saturday.

boolean
Example
true
sun

Set to true to enable Sunday.

boolean
Example
true
thu

Set to true to enable Thursday.

boolean
Example
true
tue

Set to true to enable Tuesday.

boolean
Example
true
wed

Set to true to enable Wednesday.

boolean
Example
true
Example
{
  "disabled": true,
  "fri": true,
  "mon": true,
  "sat": true,
  "sun": true,
  "thu": true,
  "tue": true,
  "wed": true
}
Example
{
  "daysOfWeek": {
    "disabled": true,
    "fri": true,
    "mon": true,
    "sat": true,
    "sun": true,
    "thu": true,
    "tue": true,
    "wed": true
  }
}
availableDaysOfWeekRateQualifier

Optional: restrict promotion to specific days of the week when it is available for booking.

object
daysOfWeek
required

The days of the week when this rate is available for booking

object
disabled

Convenience property to quickly determine if this existing object has any active days enabled.

boolean
Example
true
fri

Set to true to enable Friday.

boolean
Example
true
mon

Set to true to enable Monday.

boolean
Example
true
sat

Set to true to enable Saturday.

boolean
Example
true
sun

Set to true to enable Sunday.

boolean
Example
true
thu

Set to true to enable Thursday.

boolean
Example
true
tue

Set to true to enable Tuesday.

boolean
Example
true
wed

Set to true to enable Wednesday.

boolean
Example
true
Example
{
  "disabled": true,
  "fri": true,
  "mon": true,
  "sat": true,
  "sun": true,
  "thu": true,
  "tue": true,
  "wed": true
}
Example
{
  "daysOfWeek": {
    "disabled": true,
    "fri": true,
    "mon": true,
    "sat": true,
    "sun": true,
    "thu": true,
    "tue": true,
    "wed": true
  }
}
blackoutDates

Optional: blackout dates when promotion is not applicable.

Array<object>

A date range during which a promotion is not available (blackout period).

object
effectiveDate
required

Start date when the promotion is not available (inclusive).

string format: date
""
Example
2026-04-13
expireDate
required

End date when the promotion is not available (inclusive).

string format: date
""
Example
2026-04-15
Example
{
  "effectiveDate": "2026-04-13",
  "expireDate": "2026-04-15"
}
cityRateQualifiers

Optional: restrict promotion to guests booking from specific cities based on their IP geolocation.

Array<object>

Qualifier that restricts a promotion to guests whose IP geolocation resolves to a specific city.

object
city
required

City details (obtained via geonames) to restrict the promotion by guest location.

object
cityName
required

City name

string
"" >= 1 characters
Example
New York
continentCode
required

Continent code

string
"" >= 1 characters
Example
NA
continentName
required

Continent name

string
"" >= 1 characters
Example
North America
countryIsoCode
required

Country ISO code

string
"" >= 1 characters /^[A-Z]{2}$/
Example
US
countryName
required

Country name

string
"" >= 1 characters
Example
United States
geoNameId
required

GeoNameLightweight identifiers taken from https://geonames.org.

string
"" >= 1 characters
Example
8798734
localeCode
required

Locale code

string
"" >= 1 characters /^[a-z]{2}(-[A-Z]{2})?$/
Example
en
subDivision1Code

Sub-division 1 code

string
""
Example
NY
subDivision1Name

Sub-division 1 name

string
""
Example
NY
subDivision2Code

Sub-division 2 code

string
""
Example
Kings
subDivision2Name

Sub-division 2 name

string
""
Example
Kings County
timezone
required

Timezone

string
"" >= 1 characters
Example
America/New_York
Example
{
  "cityName": "Bangkok",
  "continentCode": "AS",
  "continentName": "Asia",
  "countryIsoCode": "TH",
  "countryName": "Thailand",
  "geoNameId": "1609350",
  "localeCode": "en",
  "subDivision1Code": "10",
  "subDivision1Name": "Bangkok",
  "subDivision2Code": "1001",
  "subDivision2Name": "Phra Nakhon",
  "timezone": "Asia/Bangkok"
}
Example
{
  "city": {
    "countryCode": "TH",
    "geoNameId": "1609350",
    "latitude": 13.7563,
    "longitude": 100.5018,
    "name": "Bangkok"
  }
}
continentRateQualifiers

Optional: restrict promotion to guests from specific continents based on their IP geolocation.

Array<object>

Qualifier that restricts a promotion to guests whose IP geolocation resolves to a specific continent.

object
continent
required

Two-letter continent code (e.g. NA, EU, AS)

string
"" >= 1 characters
Example
NA
Example
{
  "continent": "NA"
}
countryRateQualifiers

Optional: restrict promotion to guests from specific countries based on their IP geolocation.

Array<object>

Qualifier that restricts a promotion to guests whose IP geolocation resolves to a specific country.

object
country
required

Country (obtained via geonames) to restrict the promotion by guest location.

object
continentCode

Continent code (two-letter ISO)

string
""
Example
AS
continentName

Continent name

string
""
Example
Asia
countryIsoCode

Country ISO 3166-1 alpha-2 code

string
"" /^[A-Z]{2}$/
Example
TH
countryName

Country name

string
""
Example
Thailand
geoNameId

GeoNames identifier

string
""
Example
1609350
Example
{
  "continentCode": "AS",
  "continentName": "Asia",
  "countryIsoCode": "TH",
  "countryName": "Thailand",
  "geoNameId": "1609350"
}
Example
{
  "country": {
    "continentCode": "AS",
    "geoNameId": "1609350",
    "isoAlpha2": "TH",
    "isoAlpha3": "THA",
    "name": "Thailand"
  }
}
departureDaysOfWeekRateQualifier

Optional: restrict promotion to guests departing on specific days of the week.

object
daysOfWeek
required

The days of the week when the guest is allowed to depart

object
disabled

Convenience property to quickly determine if this existing object has any active days enabled.

boolean
Example
true
fri

Set to true to enable Friday.

boolean
Example
true
mon

Set to true to enable Monday.

boolean
Example
true
sat

Set to true to enable Saturday.

boolean
Example
true
sun

Set to true to enable Sunday.

boolean
Example
true
thu

Set to true to enable Thursday.

boolean
Example
true
tue

Set to true to enable Tuesday.

boolean
Example
true
wed

Set to true to enable Wednesday.

boolean
Example
true
Example
{
  "disabled": true,
  "fri": true,
  "mon": true,
  "sat": true,
  "sun": true,
  "thu": true,
  "tue": true,
  "wed": true
}
Example
{
  "daysOfWeek": {
    "disabled": true,
    "fri": true,
    "mon": true,
    "sat": true,
    "sun": true,
    "thu": true,
    "tue": true,
    "wed": true
  }
}
descriptions
required

Localized descriptions to display to guests (at least one in English). Describe the promotion’s benefits and terms.

Array<object>
"" >= 1 items <= 2147483647 items

Simplified localized description containing text content and its language code.

object
creator

Whether it was user or system generated.

string
default: USER
Allowed values: SYSTEM USER
Example
SYSTEM
description
required

Longer text description

string
"" >= 1 characters <= 2147483647 characters
Example
This is a longer description in the specified language.
hashMismatch
boolean
language
required

Indicate which language this description is written in.

string
default: en >= 2 characters <= 2 characters /^[a-z]{2}(-[A-Z]{2})?$/
Example
en
md5ContentHash

The md5 hash of the name, description and language.

string
""
Example
d41d8cd98f00b204e9800998ecf8427e
Example
{
  "creator": "USER",
  "description": "This is a longer description in the specified language.",
  "language": "en",
  "md5ContentHash": "d41d8cd98f00b204e9800998ecf8427e"
}
enabled
required

Enable or disable the promotion without deleting it.

boolean
default: true
Example
true
geoLocationRateQualifiers

Optional: restrict promotion to guests located within a circular area on the map.

Array<object>

Qualifier that restricts a promotion to guests within a circular geographic area defined by a center point and radius.

object
latitude
required

Latitude of the center point for the geo-location radius check.

number format: double
""
Example
13.7563
longitude
required

Longitude of the center point for the geo-location radius check.

number format: double
""
Example
100.5018
radiusInKilometers
required

Radius in kilometers around the center point within which the guest must be located.

integer format: int32
""
Example
50
Example
{
  "latitude": 13.7563,
  "longitude": 100.5018,
  "radiusInKilometers": 50
}
ipRangeRateQualifiers

Optional: restrict promotion to guests whose IP address falls within specified ranges.

Array<object>

Qualifier that restricts a promotion to guests whose IP address falls within a specified IPv4 range.

object
endIPRange
required

Ending IP address of the range (inclusive).

string
"" >= 1 characters
Example
192.168.1.255
startIPRange
required

Starting IP address of the range (inclusive).

string
"" >= 1 characters
Example
192.168.1.0
Example
{
  "endIPRange": "192.168.1.255",
  "startIPRange": "192.168.1.0"
}
lastMinuteRateQualifier

Optional: apply only to last-minute bookings (within X minutes of stay start date).

object
seconds
required

Number of seconds before the arrival date when the promotion becomes active (last-minute bookings).

integer format: int64
""
Example
1440
Example
{
  "seconds": 1440
}
lengthOfStayRateQualifier

Optional: restrict promotion to stays of a specific duration.

object
maxLOS
required

Maximum number of nights. Set to 0 for no maximum.

integer format: int32
""
Example
30
minLOS
required

Minimum number of nights for promotion to apply. Set to 0 for no minimum.

integer format: int32
""
Example
3
Example
{
  "maxLOS": 30,
  "minLOS": 3
}
masterRateIdentifiers

Optional: apply promotion only to specific master rates (room types).

Array<string>
modifier
required

The discount or premium amount and currency.

object
fixedAmount

A localized amount, always non-negative. Direction (surcharge vs. discount) is determined by which field this charge is assigned to, not the sign of this value.

object
amount
required

Monetary amount value

number
""
Example
1250
currency
required

ISO 4217 currency code

string
"" >= 1 characters /^[A-Z]{3}$/
Example
USD
Example
{
  "amount": 1250,
  "currency": "USD"
}
percent

A fraction between 0 and 1 (inclusive) representing a percentage of the total stay amount for an early check-in or late check-out, e.g. 0.25 for 25%. Direction (surcharge vs. discount) is determined by which field this charge is assigned to, not the sign of this value.

number format: float
"" <= 1
Example
0.25
type
required

When the type is FIXED, fixedAmount is required. When the type is PERCENTAGE, percent is required.

string
""
Allowed values: FIXED PERCENTAGE
Example
PERCENTAGE
Example
{
  "fixedAmount": {
    "amount": 1250,
    "currency": "USD"
  },
  "percent": 0.25,
  "type": "PERCENTAGE"
}
name
required

Internal name of promotion for property staff reference.

string
"" >= 1 characters
Example
Early Bird Discount
prepayRateQualifier

Optional: apply only to prepaid or non-prepaid rates.

object
prepay
required

True to apply only to prepaid rates, false to apply only to pay-at-property rates.

boolean
Example
true
Example
{
  "prepay": true
}
pricingType
required

Determines how the discount is applied: per night, per entire stay, or per guest.

string
""
Allowed values: PER_STAY PER_DAY PER_NIGHT PER_USE PER_HOUR PER_PERSON PER_PERSON_PER_NIGHT PER_PERSON_PER_HOUR PER_ADULT PER_ADULT_PER_NIGHT PER_ADULT_PER_HOUR PER_CHILD PER_CHILD_PER_NIGHT PER_CHILD_PER_HOUR
Example
PER_PERSON_PER_NIGHT
promotionRateQualifiers

Optional: require guests to enter a promo code to access this promotion.

Array<object>

Qualifier that restricts a promotion to guests who enter a specific promotional code at checkout.

object
promotion
required

Promo code that guests must enter to access this promotion.

string
"" >= 1 characters
Example
EARLYBIRD2026
Example
{
  "promotion": "EARLYBIRD2026"
}
ratePlanIdentifiers

Optional: apply promotion only to specific rate plans.

Array<string>
refundableRateQualifier

Optional: apply only to refundable or non-refundable rates.

object
refundable
required

True to apply only to refundable rates, false to apply only to non-refundable rates.

boolean
Example
true
Example
{
  "refundable": true
}
requiredDaysOfWeekRateQualifier

Optional: restrict promotion to stays that include specific days of the week.

object
daysOfWeek
required

The days of the week the user has to stay on to get this rate

object
disabled

Convenience property to quickly determine if this existing object has any active days enabled.

boolean
Example
true
fri

Set to true to enable Friday.

boolean
Example
true
mon

Set to true to enable Monday.

boolean
Example
true
sat

Set to true to enable Saturday.

boolean
Example
true
sun

Set to true to enable Sunday.

boolean
Example
true
thu

Set to true to enable Thursday.

boolean
Example
true
tue

Set to true to enable Tuesday.

boolean
Example
true
wed

Set to true to enable Wednesday.

boolean
Example
true
Example
{
  "disabled": true,
  "fri": true,
  "mon": true,
  "sat": true,
  "sun": true,
  "thu": true,
  "tue": true,
  "wed": true
}
Example
{
  "daysOfWeek": {
    "disabled": true,
    "fri": true,
    "mon": true,
    "sat": true,
    "sun": true,
    "thu": true,
    "tue": true,
    "wed": true
  }
}
roomRangeRateQualifier

Optional: restrict promotion based on number of rooms in the booking.

object
maxRooms

Maximum number of rooms in the booking. Leave null or 0 for no upper limit.

integer format: int32
""
Example
4
minRooms
required

Minimum number of rooms in the booking for this promotion to apply.

integer format: int32
"" >= 1
Example
1
Example
{
  "maxRooms": 4,
  "minRooms": 1
}
sellDateRateQualifiers

Optional: restrict promotion to specific dates when the booking is made.

Array<object>

Qualifier that restricts a promotion to bookings made within a specific date window.

object
effectiveDate
required

Promotion is available when the booking is made on or after this date (inclusive).

string format: date
""
Example
2026-05-01
expireDate
required

Promotion is available when the booking is made on or before this date (inclusive).

string format: date
""
Example
2026-08-31
Example
{
  "effectiveDate": "2026-05-01",
  "expireDate": "2026-08-31"
}
stayDateRateQualifiers

Optional: restrict promotion to specific arrival dates.

Array<object>

Rate qualifier that restricts a promotion to guests whose stay falls within a specific date range.

object
effectiveDate
required

Promotion applies when guest’s stay starts on or after this date (inclusive).

string format: date
""
Example
2026-06-01
expireDate
required

Promotion applies when guest’s stay starts on or before this date (inclusive).

string format: date
""
Example
2026-08-31
Example
{
  "effectiveDate": "2026-06-01",
  "expireDate": "2026-08-31"
}
timezoneRateQualifiers

Optional: restrict promotion to guests in specific time zones.

Array<object>

Qualifier that restricts a promotion to guests whose system timezone matches the specified IANA timezone name.

object
timezone
required

IANA timezone name of the booker’s location (e.g. Asia/Bangkok).

string
"" >= 1 characters
Example
Asia/Bangkok
Example
{
  "timezone": "Asia/Bangkok"
}
type
required

Set whether the discount should reduce the rate (DISCOUNT) or increase it as a premium (PREMIUM).

string
""
Allowed values: PREMIUM DISCOUNT
Example
DISCOUNT
Example
{
  "addOnIdentifiers": [
    "880e8400-e29b-41d4-a716-446655440333"
  ],
  "advanceBookingRateQualifier": {
    "maxAdvanceBookingOffset": 365,
    "minAdvanceBookingOffset": 7
  },
  "arrivalDaysOfWeekRateQualifier": {
    "daysOfWeek": {
      "disabled": true,
      "fri": true,
      "mon": true,
      "sat": true,
      "sun": true,
      "thu": true,
      "tue": true,
      "wed": true
    }
  },
  "availableDaysOfWeekRateQualifier": {
    "daysOfWeek": {
      "disabled": true,
      "fri": true,
      "mon": true,
      "sat": true,
      "sun": true,
      "thu": true,
      "tue": true,
      "wed": true
    }
  },
  "blackoutDates": [
    {
      "effectiveDate": "2026-04-13",
      "expireDate": "2026-04-15"
    }
  ],
  "cityRateQualifiers": [
    {
      "city": {
        "countryCode": "TH",
        "geoNameId": "1609350",
        "latitude": 13.7563,
        "longitude": 100.5018,
        "name": "Bangkok"
      }
    }
  ],
  "continentRateQualifiers": [
    {
      "continent": "NA"
    }
  ],
  "countryRateQualifiers": [
    {
      "country": {
        "continentCode": "AS",
        "geoNameId": "1609350",
        "isoAlpha2": "TH",
        "isoAlpha3": "THA",
        "name": "Thailand"
      }
    }
  ],
  "departureDaysOfWeekRateQualifier": {
    "daysOfWeek": {
      "disabled": true,
      "fri": true,
      "mon": true,
      "sat": true,
      "sun": true,
      "thu": true,
      "tue": true,
      "wed": true
    }
  },
  "descriptions": [
    {
      "creator": "USER",
      "description": "This is a longer description in the specified language.",
      "language": "en",
      "md5ContentHash": "d41d8cd98f00b204e9800998ecf8427e"
    }
  ],
  "enabled": true,
  "geoLocationRateQualifiers": [
    {
      "latitude": 13.7563,
      "longitude": 100.5018,
      "radiusInKilometers": 50
    }
  ],
  "ipRangeRateQualifiers": [
    {
      "endIPRange": "192.168.1.255",
      "startIPRange": "192.168.1.0"
    }
  ],
  "lastMinuteRateQualifier": {
    "seconds": 1440
  },
  "lengthOfStayRateQualifier": {
    "maxLOS": 30,
    "minLOS": 3
  },
  "masterRateIdentifiers": [
    "770e8400-e29b-41d4-a716-446655440222"
  ],
  "modifier": {
    "fixedAmount": {
      "amount": 1250,
      "currency": "USD"
    },
    "percent": 0.25,
    "type": "PERCENTAGE"
  },
  "name": "Early Bird Discount",
  "prepayRateQualifier": {
    "prepay": true
  },
  "pricingType": "PER_PERSON_PER_NIGHT",
  "promotionRateQualifiers": [
    {
      "promotion": "EARLYBIRD2026"
    }
  ],
  "ratePlanIdentifiers": [
    "990e8400-e29b-41d4-a716-446655440444"
  ],
  "refundableRateQualifier": {
    "refundable": true
  },
  "requiredDaysOfWeekRateQualifier": {
    "daysOfWeek": {
      "disabled": true,
      "fri": true,
      "mon": true,
      "sat": true,
      "sun": true,
      "thu": true,
      "tue": true,
      "wed": true
    }
  },
  "roomRangeRateQualifier": {
    "maxRooms": 4,
    "minRooms": 1
  },
  "sellDateRateQualifiers": [
    {
      "effectiveDate": "2026-05-01",
      "expireDate": "2026-08-31"
    }
  ],
  "stayDateRateQualifiers": [
    {
      "effectiveDate": "2026-06-01",
      "expireDate": "2026-08-31"
    }
  ],
  "timezoneRateQualifiers": [
    {
      "timezone": "Asia/Bangkok"
    }
  ],
  "type": "DISCOUNT"
}

Responses

Section titled “Responses”

200

Section titled “200”

Promotion updated successfully.

Media typeapplication/json

A lightweight projection of a special rate (promotion) containing all qualifying conditions and metadata.

object
addOnIdentifiers
Array<string>
advanceBookingRateQualifier

Restrict promotion to users who want to book in advance.

object
maxAdvanceBookingOffset

Maximum days in advance of stay start date when the booking may be made. Set to 0 for no maximum.

integer format: int32
""
minAdvanceBookingOffset

Minimum days in advance of stay start date when the booking must be made. Set to 0 for no minimum.

integer format: int32
""
arrivalDaysOfWeekRateQualifier

Restrict promotion to specific days of the week the guest is arriving.

object
daysOfWeek
required

The days of the week when this rate is available for guests to arrive on

object
disabled

Convenience property to quickly determine if this existing object has any active days enabled.

boolean
fri

Set to true to enable Friday.

boolean
mon

Set to true to enable Monday.

boolean
sat

Set to true to enable Saturday.

boolean
sun

Set to true to enable Sunday.

boolean
thu

Set to true to enable Thursday.

boolean
tue

Set to true to enable Tuesday.

boolean
wed

Set to true to enable Wednesday.

boolean
availableDaysOfWeekRateQualifier

Restrict promotion to specific days of the week the promotion is available.

object
daysOfWeek
required

The days of the week when this rate is available for booking

object
disabled

Convenience property to quickly determine if this existing object has any active days enabled.

boolean
fri

Set to true to enable Friday.

boolean
mon

Set to true to enable Monday.

boolean
sat

Set to true to enable Saturday.

boolean
sun

Set to true to enable Sunday.

boolean
thu

Set to true to enable Thursday.

boolean
tue

Set to true to enable Tuesday.

boolean
wed

Set to true to enable Wednesday.

boolean
blackoutDates
Array<object>

A date range during which a promotion is not available (blackout period).

object
effectiveDate
required

Start date when the promotion is not available (inclusive).

string format: date
""
expireDate
required

End date when the promotion is not available (inclusive).

string format: date
""
cityRateQualifiers
Array<object>

Qualifier that restricts a promotion to guests whose IP geolocation resolves to a specific city.

object
city
required

City details (obtained via geonames) to restrict the promotion by guest location.

object
cityName
required

City name

string
"" >= 1 characters
continentCode
required

Continent code

string
"" >= 1 characters
continentName
required

Continent name

string
"" >= 1 characters
countryIsoCode
required

Country ISO code

string
"" >= 1 characters /^[A-Z]{2}$/
countryName
required

Country name

string
"" >= 1 characters
geoNameId
required

GeoNameLightweight identifiers taken from https://geonames.org.

string
"" >= 1 characters
localeCode
required

Locale code

string
"" >= 1 characters /^[a-z]{2}(-[A-Z]{2})?$/
subDivision1Code

Sub-division 1 code

string
""
subDivision1Name

Sub-division 1 name

string
""
subDivision2Code

Sub-division 2 code

string
""
subDivision2Name

Sub-division 2 name

string
""
timezone
required

Timezone

string
"" >= 1 characters
continentRateQualifiers
Array<object>

Qualifier that restricts a promotion to guests whose IP geolocation resolves to a specific continent.

object
continent
required

Two-letter continent code (e.g. NA, EU, AS)

string
"" >= 1 characters
countryRateQualifiers
Array<object>

Qualifier that restricts a promotion to guests whose IP geolocation resolves to a specific country.

object
country
required

Country (obtained via geonames) to restrict the promotion by guest location.

object
continentCode

Continent code (two-letter ISO)

string
""
continentName

Continent name

string
""
countryIsoCode

Country ISO 3166-1 alpha-2 code

string
"" /^[A-Z]{2}$/
countryName

Country name

string
""
geoNameId

GeoNames identifier

string
""
createdDate

Datetime this record was first created

string | null format: date-time
""
departureDaysOfWeekRateQualifier

Restrict promotion to specific days of the week the guest is departing.

object
daysOfWeek
required

The days of the week when the guest is allowed to depart

object
disabled

Convenience property to quickly determine if this existing object has any active days enabled.

boolean
fri

Set to true to enable Friday.

boolean
mon

Set to true to enable Monday.

boolean
sat

Set to true to enable Saturday.

boolean
sun

Set to true to enable Sunday.

boolean
thu

Set to true to enable Thursday.

boolean
tue

Set to true to enable Tuesday.

boolean
wed

Set to true to enable Wednesday.

boolean
descriptions
required
Array<object>
>= 1 items

Simplified localized description containing text content and its language code.

object
creator

Whether it was user or system generated.

string
default: USER
Allowed values: SYSTEM USER
description
required

Longer text description

string
"" >= 1 characters <= 2147483647 characters
hashMismatch
boolean
language
required

Indicate which language this description is written in.

string
default: en >= 2 characters <= 2 characters /^[a-z]{2}(-[A-Z]{2})?$/
md5ContentHash

The md5 hash of the name, description and language.

string
""
enabled
required

Whether this promotion is enabled or not.

boolean
default: true
geoLocationRateQualifiers
Array<object>

Qualifier that restricts a promotion to guests within a circular geographic area defined by a center point and radius.

object
latitude
required

Latitude of the center point for the geo-location radius check.

number format: double
""
longitude
required

Longitude of the center point for the geo-location radius check.

number format: double
""
radiusInKilometers
required

Radius in kilometers around the center point within which the guest must be located.

integer format: int32
""
hotelIdentifier
required

Unique identifier of the property this promotion belongs to.

string format: uuid
"" >= 1 characters
id
required

Unique identifier for this record.

string format: uuid
"" >= 1 characters
ipRangeRateQualifiers
Array<object>

Qualifier that restricts a promotion to guests whose IP address falls within a specified IPv4 range.

object
endIPRange
required

Ending IP address of the range (inclusive).

string
"" >= 1 characters
startIPRange
required

Starting IP address of the range (inclusive).

string
"" >= 1 characters
lastMinuteRateQualifier

Restrict promotion to users who want to book a room close to the date.

object
seconds
required

Number of seconds before the arrival date when the promotion becomes active (last-minute bookings).

integer format: int64
""
lastUpdate

Datetime this record was last updated

string | null format: date-time
""
lengthOfStayRateQualifier

Restrict promotion to users who want to stay a certain number of days.

object
maxLOS
required

Maximum number of nights. Set to 0 for no maximum.

integer format: int32
""
minLOS
required

Minimum number of nights for promotion to apply. Set to 0 for no minimum.

integer format: int32
""
masterRateIdentifiers
Array<string>
modifier
required

The discount or premium amount and its type (fixed or percentage).

object
fixedAmount

A localized amount, always non-negative. Direction (surcharge vs. discount) is determined by which field this charge is assigned to, not the sign of this value.

object
amount
required

Monetary amount value

number
""
currency
required

ISO 4217 currency code

string
"" >= 1 characters /^[A-Z]{3}$/
percent

A fraction between 0 and 1 (inclusive) representing a percentage of the total stay amount for an early check-in or late check-out, e.g. 0.25 for 25%. Direction (surcharge vs. discount) is determined by which field this charge is assigned to, not the sign of this value.

number format: float
"" <= 1
type
required

When the type is FIXED, fixedAmount is required. When the type is PERCENTAGE, percent is required.

string
""
Allowed values: FIXED PERCENTAGE
name
required

Internal name of promotion.

string
"" >= 1 characters
prepayRateQualifier

Restrict promotion to either prepaid / non-prepaid rates.

object
prepay
required

True to apply only to prepaid rates, false to apply only to pay-at-property rates.

boolean
pricingType
required

This determines whether this discount should be applied per night, per stay or per person - per night

string
""
Allowed values: PER_STAY PER_DAY PER_NIGHT PER_USE PER_HOUR PER_PERSON PER_PERSON_PER_NIGHT PER_PERSON_PER_HOUR PER_ADULT PER_ADULT_PER_NIGHT PER_ADULT_PER_HOUR PER_CHILD PER_CHILD_PER_NIGHT PER_CHILD_PER_HOUR
promotionRateQualifiers
Array<object>

Qualifier that restricts a promotion to guests who enter a specific promotional code at checkout.

object
promotion
required

Promo code that guests must enter to access this promotion.

string
"" >= 1 characters
ratePlanIdentifiers
Array<string>
refundableRateQualifier

Restrict promotion to either refundable / non-refundable rates.

object
refundable
required

True to apply only to refundable rates, false to apply only to non-refundable rates.

boolean
requiredDaysOfWeekRateQualifier

Restrict promotion to specific days of the week the guest has to stay.

object
daysOfWeek
required

The days of the week the user has to stay on to get this rate

object
disabled

Convenience property to quickly determine if this existing object has any active days enabled.

boolean
fri

Set to true to enable Friday.

boolean
mon

Set to true to enable Monday.

boolean
sat

Set to true to enable Saturday.

boolean
sun

Set to true to enable Sunday.

boolean
thu

Set to true to enable Thursday.

boolean
tue

Set to true to enable Tuesday.

boolean
wed

Set to true to enable Wednesday.

boolean
roomRangeRateQualifier

Restrict promotion by restricting to how many rooms the user wants.

object
maxRooms

Maximum number of rooms in the booking. Leave null or 0 for no upper limit.

integer format: int32
""
minRooms
required

Minimum number of rooms in the booking for this promotion to apply.

integer format: int32
"" >= 1
sellDateRateQualifiers
Array<object>

Qualifier that restricts a promotion to bookings made within a specific date window.

object
effectiveDate
required

Promotion is available when the booking is made on or after this date (inclusive).

string format: date
""
expireDate
required

Promotion is available when the booking is made on or before this date (inclusive).

string format: date
""
stayDateRateQualifiers
Array<object>

Rate qualifier that restricts a promotion to guests whose stay falls within a specific date range.

object
effectiveDate
required

Promotion applies when guest’s stay starts on or after this date (inclusive).

string format: date
""
expireDate
required

Promotion applies when guest’s stay starts on or before this date (inclusive).

string format: date
""
timezoneRateQualifiers
Array<object>

Qualifier that restricts a promotion to guests whose system timezone matches the specified IANA timezone name.

object
timezone
required

IANA timezone name of the booker’s location (e.g. Asia/Bangkok).

string
"" >= 1 characters
type
required

Set whether you want the price to go up or down when the rules of this promotion have been satisfied.

string
""
Allowed values: PREMIUM DISCOUNT
version

Optimistic-locking version. Echo this value back as an If-Match request header on a conditional update; the server responds 409 if the record changed in the meantime. Null when this projection has no backing versioned document, in which case no conditional update is possible.

integer | null format: int64
""
key
additional properties
""
Example
{
  "addOnIdentifiers": [
    "880e8400-e29b-41d4-a716-446655440333"
  ],
  "advanceBookingRateQualifier": {
    "maxAdvanceBookingOffset": 365,
    "minAdvanceBookingOffset": 7
  },
  "arrivalDaysOfWeekRateQualifier": {
    "daysOfWeek": {
      "disabled": true,
      "fri": true,
      "mon": true,
      "sat": true,
      "sun": true,
      "thu": true,
      "tue": true,
      "wed": true
    }
  },
  "availableDaysOfWeekRateQualifier": {
    "daysOfWeek": {
      "disabled": true,
      "fri": true,
      "mon": true,
      "sat": true,
      "sun": true,
      "thu": true,
      "tue": true,
      "wed": true
    }
  },
  "blackoutDates": [
    {
      "effectiveDate": "2026-04-13",
      "expireDate": "2026-04-15"
    }
  ],
  "cityRateQualifiers": [
    {
      "city": {
        "countryCode": "TH",
        "geoNameId": "1609350",
        "latitude": 13.7563,
        "longitude": 100.5018,
        "name": "Bangkok"
      }
    }
  ],
  "continentRateQualifiers": [
    {
      "continent": "NA"
    }
  ],
  "countryRateQualifiers": [
    {
      "country": {
        "continentCode": "AS",
        "geoNameId": "1609350",
        "isoAlpha2": "TH",
        "isoAlpha3": "THA",
        "name": "Thailand"
      }
    }
  ],
  "createdDate": "2026-01-14T09:30:00",
  "departureDaysOfWeekRateQualifier": {
    "daysOfWeek": {
      "disabled": true,
      "fri": true,
      "mon": true,
      "sat": true,
      "sun": true,
      "thu": true,
      "tue": true,
      "wed": true
    }
  },
  "descriptions": [
    {
      "creator": "USER",
      "description": "This is a longer description in the specified language.",
      "language": "en",
      "md5ContentHash": "d41d8cd98f00b204e9800998ecf8427e"
    }
  ],
  "enabled": true,
  "geoLocationRateQualifiers": [
    {
      "latitude": 13.7563,
      "longitude": 100.5018,
      "radiusInKilometers": 50
    }
  ],
  "hotelIdentifier": "e2c7b4d3-1a8f-4e9c-b5d6-3a9f0e7c2b18",
  "id": "b7e4c1a2-3f5d-4e8a-9c21-6f0b5d8e3a47",
  "ipRangeRateQualifiers": [
    {
      "endIPRange": "192.168.1.255",
      "startIPRange": "192.168.1.0"
    }
  ],
  "lastMinuteRateQualifier": {
    "seconds": 1440
  },
  "lastUpdate": "2026-02-03T16:45:12",
  "lengthOfStayRateQualifier": {
    "maxLOS": 30,
    "minLOS": 3
  },
  "masterRateIdentifiers": [
    "770e8400-e29b-41d4-a716-446655440222"
  ],
  "modifier": {
    "fixedAmount": {
      "amount": 1250,
      "currency": "USD"
    },
    "percent": 0.25,
    "type": "PERCENTAGE"
  },
  "name": "Early bird",
  "prepayRateQualifier": {
    "prepay": true
  },
  "pricingType": "PER_PERSON_PER_NIGHT",
  "promotionRateQualifiers": [
    {
      "promotion": "EARLYBIRD2026"
    }
  ],
  "ratePlanIdentifiers": [
    "990e8400-e29b-41d4-a716-446655440444"
  ],
  "refundableRateQualifier": {
    "refundable": true
  },
  "requiredDaysOfWeekRateQualifier": {
    "daysOfWeek": {
      "disabled": true,
      "fri": true,
      "mon": true,
      "sat": true,
      "sun": true,
      "thu": true,
      "tue": true,
      "wed": true
    }
  },
  "roomRangeRateQualifier": {
    "maxRooms": 4,
    "minRooms": 1
  },
  "sellDateRateQualifiers": [
    {
      "effectiveDate": "2026-05-01",
      "expireDate": "2026-08-31"
    }
  ],
  "stayDateRateQualifiers": [
    {
      "effectiveDate": "2026-06-01",
      "expireDate": "2026-08-31"
    }
  ],
  "timezoneRateQualifiers": [
    {
      "timezone": "Asia/Bangkok"
    }
  ],
  "type": "DISCOUNT",
  "version": 3
}

400

Section titled “400”

Bad Request — missing or invalid request parameter or body

Media typeapplication/problem+json
object
detail
string
instance
string format: uri
properties
object
key
additional properties
status
integer format: int32
title
string
type
string format: uri
key
additional properties
""
Example

401

Section titled “401”

Unauthorized — authentication is required or the session has expired

Media typeapplication/problem+json
object
detail
string
instance
string format: uri
properties
object
key
additional properties
status
integer format: int32
title
string
type
string format: uri
key
additional properties
""
Example

403

Section titled “403”

Forbidden — authenticated but lacking the required permission or scope

Media typeapplication/problem+json
object
detail
string
instance
string format: uri
properties
object
key
additional properties
status
integer format: int32
title
string
type
string format: uri
key
additional properties
""
Example

404

Section titled “404”

Not Found — the requested resource does not exist

Media typeapplication/problem+json
object
detail
string
instance
string format: uri
properties
object
key
additional properties
status
integer format: int32
title
string
type
string format: uri
key
additional properties
""
Example

405

Section titled “405”

Method Not Allowed — the HTTP verb is not supported on this endpoint

Media typeapplication/problem+json
object
detail
string
instance
string format: uri
properties
object
key
additional properties
status
integer format: int32
title
string
type
string format: uri
key
additional properties
""
Example

409

Section titled “409”

Conflict — the resource was modified by someone else since you read it; re-read it and retry with the new version

Media typeapplication/problem+json
object
detail
string
instance
string format: uri
properties
object
key
additional properties
status
integer format: int32
title
string
type
string format: uri
key
additional properties
""
Example

415

Section titled “415”

Unsupported Media Type — use application/json

Media typeapplication/problem+json
object
detail
string
instance
string format: uri
properties
object
key
additional properties
status
integer format: int32
title
string
type
string format: uri
key
additional properties
""
Example

500

Section titled “500”

Internal Server Error — an unexpected failure occurred on the server

Media typeapplication/problem+json
object
detail
string
instance
string format: uri
properties
object
key
additional properties
status
integer format: int32
title
string
type
string format: uri
key
additional properties
""
Example

503

Section titled “503”

Service Unavailable — a downstream dependency is unreachable

Media typeapplication/problem+json
object
detail
string
instance
string format: uri
properties
object
key
additional properties
status
integer format: int32
title
string
type
string format: uri
key
additional properties
""
Example