Gap Price Adjustments

Endpoint	Method	Scope	Description
/api/v1/listings/<id>/customizations/gap-price-adjustments/	GET	listings:read	Get gap price adjustments customization for a listing
/api/v1/listings/<id>/customizations/gap-price-adjustments/	PATCH	listings:write	Update gap price 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.

Use gap-price-adjustments to price the nights of short open gaps between two bookings, which are hard to fill at the full rate. Like time-based adjustments, it supports two operating modes: dynamic and manual.

A GET returns the dynamic setting, the listing's manual rules, whether those are Beyond's defaults, and the default rules themselves:

{
  "data": {
    "type": "gap-price-adjustment-customizations",
    "id": "123",
    "attributes": {
      "dynamic-gap-price-adjustments": {"enabled": false},
      "gap-price-adjustments": [
        {"days": 1, "percentage": -29, "excluded-days-of-week": []},
        {"days": 2, "percentage": 15, "excluded-days-of-week": ["friday", "saturday"]}
      ],
      "is-default": false,
      "default-gap-price-adjustments": [
        {"days": 1, "percentage": -30, "excluded-days-of-week": []},
        {"days": 2, "percentage": -20, "excluded-days-of-week": ["friday"]},
        {"days": 3, "percentage": -10, "excluded-days-of-week": ["thursday", "friday"]}
      ]
    }
  }
}

Dynamic Gap Price Adjustments

When dynamic-gap-price-adjustments.enabled is true, Beyond adjusts gaps of up to 3 nights from market-specific booking trends, and the manual rules are not applied. Minimum stay rules are still honored. The feature is only available in some markets: elsewhere, a request to enable it is ignored and the response keeps enabled: false.

Manual Gap Price Adjustments

While dynamic mode is disabled, each rule in gap-price-adjustments applies to every night of an open gap of exactly days nights (1 to 32767):

• percentage: a whole-number percent applied to the night's price, where -30 means -30% and 15 means +15%. It must be between -99 and 999 and not 0.
• excluded-days-of-week: optional. Gap nights falling on these weekdays keep their unadjusted price — for example, a Friday night in a two-night gap is often easy to book. Omit it to adjust every night of the gap.

Two rules for the same days must not adjust the same weekday; split the week between them with excluded-days-of-week instead.

A PATCH with gap-price-adjustments replaces the whole list: rules you leave out are removed, and an empty list removes every rule. This request switches the listing to manual mode with two rules:

{
  "data": {
    "type": "gap-price-adjustment-customizations",
    "id": "123",
    "attributes": {
      "dynamic-gap-price-adjustments": {"enabled": false},
      "gap-price-adjustments": [
        {"days": 1, "percentage": -29, "excluded-days-of-week": []},
        {"days": 2, "percentage": 15, "excluded-days-of-week": ["friday", "saturday"]}
      ]
    }
  }
}

Default Rules

default-gap-price-adjustments holds Beyond's default manual rules. They are the same for every listing and cannot be changed. A listing that never saved its own rules is priced with them: gap-price-adjustments returns them and is-default is true.

is-default becomes false once the listing saves rules that differ from the defaults. It stays false even after every rule is removed, so a listing with no rules does not fall back to the defaults. To restore them, send default-gap-price-adjustments as gap-price-adjustments: the listing then keeps them as its own rules, which price the same, and is-default stays false. Both read-only fields are ignored in a PATCH.

Manual rules cannot be changed while dynamic mode is enabled, including in the request that enables it: such a PATCH is rejected with 422. Send "dynamic-gap-price-adjustments": {"enabled": false} to change the manual rules. Rules sent unchanged, in any order, are accepted, so the body of a GET can be sent back as is.