Time-Based Adjustments

Endpoint	Method	Scope	Description
/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

Try it out

Explore schemas and live requests in the Swagger UI.

Part of Listing Customizations: its conventions and errors apply to every customization type.

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

A GET returns both the dynamic settings and any manual rules:

{
  "data": {
    "type": "time-based-adjustment-customizations",
    "id": "123",
    "attributes": {
      "dynamic-time-based-adjustments": {
        "enabled": true,
        "tier": "revenue",
        "median-lead-time": 21
      },
      "time-based-adjustments": [
        {"days": 7, "percentage": -10, "direction": "within"},
        {"days": 270, "percentage": 15, "direction": "after"}
      ],
      "seasonal-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.

median-lead-time is the median number of days between booking and arrival for listings of similar size in the listing's neighborhood, the same figure the Beyond dashboard shows next to dynamic time-based adjustments. It describes the market, not a listing setting, so it is returned whether or not dynamic time-based adjustments is enabled. It is read-only: a PATCH that sends it is accepted and the value is ignored. It is null when Beyond has no estimate for the listing's neighborhood.

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.