Listing Customizations¶

Endpoint	Method	Scope	Description
`/api/v1/listings/<id>/customizations/base-price/`	GET	`listings:read`	Get base price customization for a listing
`/api/v1/listings/<id>/customizations/base-price/`	PATCH	`listings:write`	Update base price customization for a listing
`/api/v1/listings/<id>/customizations/min-stays/`	GET	`listings:read`	Get min-stays customization for a listing
`/api/v1/listings/<id>/customizations/min-stays/`	PATCH	`listings:write`	Update min-stays customization for a listing
`/api/v1/listings/<id>/customizations/extra-guest-fees/`	GET	`listings:read`	Get extra guest fee customization for a listing
`/api/v1/listings/<id>/customizations/extra-guest-fees/`	PATCH	`listings:write`	Update extra guest fee customization for a listing
`/api/v1/listings/<id>/customizations/max-stays/`	GET	`listings:read`	Get max-stays customization for a listing
`/api/v1/listings/<id>/customizations/max-stays/`	PATCH	`listings:write`	Update max-stays customization for a listing
`/api/v1/listings/<id>/customizations/min-max-prices/`	GET	`listings:read`	Get min/max prices customization for a listing
`/api/v1/listings/<id>/customizations/min-max-prices/`	PATCH	`listings:write`	Update min/max prices customization for a listing
`/api/v1/listings/<id>/customizations/time-based-adjustments/`	GET	`listings:read`	Get time-based adjustments customization for a listing
`/api/v1/listings/<id>/customizations/time-based-adjustments/`	PATCH	`listings:write`	Update time-based adjustments customization for a listing
`/api/v1/listings/<id>/customizations/checkin-checkout-days/`	GET	`listings:read`	Get checkin/checkout days customization for a listing
`/api/v1/listings/<id>/customizations/checkin-checkout-days/`	PATCH	`listings:write`	Update checkin/checkout days customization for a listing

Try it out

Explore schemas and live requests in the Swagger UI.

Overview¶

Listing customization endpoints expose the mutable pricing and stay-rule settings that apply to a specific listing. These routes use a stable customizations/ namespace so new customization types can be added later without changing the API version.

These endpoints are listing-scoped. A future release may add a separate namespace for global default customizations.

Supported Customization Types¶

base-price: the listing's nightly base price.
min-stays: minimum-night rules for annual, seasonal, day-of-week, lead-time, and gap-fill behavior.
extra-guest-fees: per-guest fees that apply when a reservation exceeds the included guest count.
max-stays: maximum-night rules for year-round and seasonal date ranges.
min-max-prices: nightly and monthly floor and ceiling pricing, including weekday and seasonal overrides.
time-based-adjustments: lead-time discounts and premiums, either dynamic or manually configured.
checkin-checkout-days: allowed arrival and departure weekdays, including seasonal restrictions.

Conventions¶

Use GET to retrieve the current customization state for a listing.
Use PATCH to update only the fields you want to change.
Request and response bodies follow JSON:API.
Field names are dasherized in the HTTP payloads.

Base Price¶

Use base-price to set the listing's nightly base price. The base price is the anchor used by Beyond Pricing's algorithm; minimum and maximum prices, seasonal rules, and time-based adjustments are all applied relative to it.

The payload includes:

base-price: the nightly base price for the listing. Must be at least 10.

Extra Guest Fees¶

Use extra-guest-fees to charge an additional fee when a reservation exceeds the number of guests included in the standard rate.

If no extra guest fee is configured, the standard price applies.

The payload includes:

extra-guest-fee: the fee charged for each guest above the threshold.
extra-guest-threshold: the number of guests included before the fee applies.

Minimum Stays¶

Use min-stays to manage minimum-night requirements for a listing. This customization supports a combination of year-round defaults, weekday overrides, seasonal rules, lead-time rules, and gap-fill behavior.

Minimum stays are applied in the following order:

Seasonal Time-Based Minimum Stays
Time-Based Minimum Stays
Seasonal Minimum Stays
Day of Week Minimum Stays
Annual Minimum Stays

Gap fills apply across minimum stay rules to help protect short orphan gaps in availability.

Annual Minimum Stay¶

Annual Minimum Stay sets the default minimum stay across all dates except where overridden by day-of-week or seasonal rules. We recommend setting this to the shortest minimum stay you would accept during lower-demand periods.

If the annual minimum stay is left blank, it defaults to a 1-night stay.

Annual Minimum Stays By Day Of Week¶

Day-of-week minimum stays take precedence over the annual minimum stay. Days left blank inherit the annual minimum stay value.

Seasonal Minimum Stays By Day Of Week¶

Seasonal weekday minimum stays override annual rules and annual weekday rules for their date range. They are still superseded by seasonal minimum stays, time-based minimum stays, and gap-fill rules.

Seasonal Minimum Stays¶

Seasonal minimum stays let you create date-range specific rules for holidays, events, or other periods of predictable demand. These rules override annual and day-of-week minimum stays, but time-based minimum stays and gap fills still take precedence.

Time-Based Minimum Stays¶

Time-based minimum stays let you set a minimum stay based on how far away a booking is from today. These rules take precedence over seasonal minimum stays.

Seasonal Time-Based Minimum Stays¶

Seasonal time-based minimum stays let you tailor lead-time rules to specific date ranges so minimum-night requirements can vary by season.

Gap Fill Minimum Stays¶

Gap-fill settings apply minimum-stay protections around short openings between bookings. The API supports both year-round gap-fill settings and seasonal gap-fill settings.

Maximum Stays¶

Use max-stays to limit how long a guest can stay. This customization supports:

max-stay: the default maximum allowed stay, in nights.
seasonal-max-stays: date-range-specific maximum stay overrides.

Min/Max Prices¶

Use min-max-prices to define nightly and monthly price floors and ceilings for a listing.

Minimum prices are applied in this order:

seasonal-prices
seasonal-day-of-week-min-prices
day-of-week-min-prices
min-price

All minimum prices are honored by any discounting rules configured for the listing.

Annual Minimum and Maximum Prices¶

Use min-price and max-price to set default nightly minimum and maximum prices across all dates, except where a day-of-week or seasonal minimum applies. We recommend setting min-price to the lowest nightly price you would accept at any time of year.

Annual Minimum Price by Day of Week¶

Use day-of-week-min-prices to set year-round nightly minimum prices for specific weekdays. These values take precedence over min-price. Any weekday left blank uses the min-price value.

Seasonal Minimum Prices by Day of Week¶

Use seasonal-day-of-week-min-prices to set weekday-specific nightly minimum prices for a defined date range. These values take precedence over day-of-week-min-prices, but are superseded by seasonal-prices.

Seasonal Minimum and Maximum Prices¶

Use seasonal-prices to set nightly minimum and maximum prices for specific date ranges, such as holidays or events. We do not recommend limiting our recommended prices by setting a maximum price.

Time-Based Adjustments¶

The time-based-adjustments customization supports two operating modes: dynamic time-based adjustments and manual time-based adjustments.

Dynamic Time-Based Adjustments¶

Dynamic Time-Based Adjustments is a core algorithm feature. When enabled, Beyond updates the listing's discount and premium rules based on the latest booking trends for the market and property type. Keeping this enabled ensures pricing rules are optimized daily to maximize revenue.

When dynamic time-based adjustments is enabled, the user can choose one of the available optimization tiers:

revenue
occupancy
rate

revenue is the default and recommended option.

Manual Annual And Seasonal Adjustments¶

When dynamic time-based adjustments is disabled, the user can configure manual annual and seasonal time-based adjustments.

Annual Time-Based Adjustments¶

Annual time-based adjustments help shape pricing across the full booking window. Discounting dates that are coming up soon can help improve short-term occupancy. Increasing prices for dates far in the future can help achieve higher ADRs and avoid booking those dates too quickly.

We recommend always including an increase for dates more than 270 days (9 months) in the future.

Seasonal Time-Based Adjustments¶

Seasonal time-based adjustments let users tailor discounts and premiums to seasonal demand patterns. For example, you may discount more aggressively in low season and less in high season.

Annual adjustments are pre-loaded for easy customization. Users can adjust the rules as needed and save them to create a seasonal setting.

Check-In/Checkout Days¶

Use checkin-checkout-days to limit which weekdays guests may arrive or depart.

This customization supports:

checkin-days: allowed arrival weekdays year-round.
checkout-days: allowed departure weekdays year-round.
seasonal-checkin-checkout-days: date-range-specific arrival and departure rules.
changeover-days-gap-fill-enabled: whether annual or seasonal changeover-day restrictions can be overridden to keep short orphan gaps bookable, while still respecting the minimum stay for the period.