Create Calendar Rule

post

https://app.hosttools.com/api/createCalendarRule/{listingID}

Adds a calendar rule to a listing. The rule goes to the bottom of the listing's list (it applies last) unless you send a position. Prices are recalculated and sent to the listing's channels in the background. Requires the pricing:write scope.

Each scale and event takes its own fields (see the request body); a rule missing one, or with a field that doesn't fit, is refused with a 400 that names it.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

listingID

string

required

_id of the listing

Body Params

The fields of a calendar rule. Each scale and event uses only the fields named in its description.

title

string

required

Rule name, shown in Host Tools

scale

string

enum

required

What the rule does. fixedPrice, minPrice and maxPrice set the price, or a floor or ceiling on it. increaseByPrice, decreaseByPrice, increaseByPercentage and decreaseByPercentage change it by an amount or a percentage. grossUpByPercentage raises it so it is the same after a channel takes that percentage. The gradually scales step the change across the rule's dates (Reverse runs the steps backwards). minNights sets the minimum stay. availability blocks or opens dates (it applies to every channel). blockCheckin and blockCheckout stop check-ins or check-outs.

amount

number

Required for every scale except availability, blockCheckin and blockCheckout, and greater than 0: the price, the amount to change it by, the percentage, or the minimum nights (a whole number).

blocked

boolean

For availability, required: true blocks the dates, false opens them. For blockCheckin and blockCheckout: true blocks (default), false allows.

event

string

enum

required

When the rule applies. all: every date. floatingPeriod: a window that moves with today. orphanPeriod: short gaps between bookings. specificDates: a date range. afterReservation and beforeReservation: days around each booking. months: whole months. yearlyDates: the same dates every year. nthWeekday: a weekday that moves each year, such as the 4th Thursday of November.

channel

string

enum

Which channel's prices the rule changes. Defaults to all. availability rules always apply to all.

Allowed:

limitDays

array of strings

The weekdays the rule applies on. Leave it out for every day.

limitDays

Allowed:

specificDatesStartDate

string

For specificDates, required. The first night, YYYY-MM-DD.

specificDatesEndDate

string

For specificDates, required. The day after the last night, not included (like a check-out day), YYYY-MM-DD.

floatingPeriodStartDay

integer

For floatingPeriod, required. Days from today the window starts, 0 to 730 (0 is today).

floatingPeriodLength

integer

For floatingPeriod, required. How many days the window lasts, 1 to 730.

orphanPeriodLength

integer

For orphanPeriod, required. The longest gap between bookings, in nights, the rule applies to.

afterReservationLength

integer

For afterReservation. Days after each check-out, 1 to 5. Defaults to 1.

beforeReservationLength

integer

For beforeReservation. Days before each check-in, 0 to 5, where 0 is the check-in day. Defaults to 1.

months

array of strings

For months, required. The months the rule applies in.

months

yearlyDates

object

For yearlyDates, required. The same calendar dates every year, both ends included. An end earlier than the start wraps into the next year.

nthWeekday

object

For nthWeekday, required. A weekday that moves each year, plus the days around it. US Thanksgiving is {"month": 11, "week": 4, "weekday": "thursday"}.

position

integer

≥ 1

Where to put the rule in the listing's list, 1 is the top (applies first). Leave it out to add the rule at the bottom.

Headers

apiKey

string

Partner API key (deprecated — use OAuth 2.0 for new integrations)

authToken

string

User's authentication token (legacy). Use Authorization Bearer header for new integrations.

Responses

429

Too many requests

200The new calendar rule

400Error, with the reason in message