Listing Customizations¶

Endpoint	Method	Scope	Description
`/api/v1/listings/<id>/customizations/`	GET	`listings:read`	Get all customizations for a listing in one response
`/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/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/manual-overrides/`	GET	`listings:read`	Get manual price overrides for a listing
`/api/v1/listings/<id>/customizations/manual-overrides/`	PATCH	`listings:write`	Update manual price overrides 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.
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.
manual-overrides: per-date price overrides that pin or adjust the price for specific dates.

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.

All Customizations¶

GET /api/v1/listings/<id>/customizations/ returns every supported customization for a listing in a single listing-customizations resource, so partners can retrieve the full picture without one request per type.

The response is keyed by customization name, and each value is identical to the attributes returned by that customization's own GET endpoint:

base-price
extra-guest-fees
min-max-prices
min-stays
time-based-adjustments

To retrieve only a subset, use the JSON:API sparse fieldset query parameter fields[listing-customizations] with a comma-separated list of customization names. For example:

GET /api/v1/listings/123/customizations/?fields[listing-customizations]=base-price,min-stays

returns only the base-price and min-stays customizations. This endpoint is read-only; continue to use the individual customizations/<type>/ endpoints with PATCH to make changes.

manual-overrides is deliberately not part of this aggregate: it is keyed by date rather than by rule, so a single listing can carry hundreds of rows. Read it from its own endpoint, where you can also narrow the date range.

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, in the listing's currency. Must be at least 10.

{
  "data": {
    "type": "base-price-customizations",
    "id": "123",
    "attributes": {
      "base-price": 189
    }
  }
}

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, in the listing's currency.
extra-guest-threshold: the number of guests included before the fee applies.

{
  "data": {
    "type": "extra-guest-fee-customizations",
    "id": "123",
    "attributes": {
      "extra-guest-fee": 25,
      "extra-guest-threshold": 4
    }
  }
}

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.

A GET returns every rule family. Unconfigured families come back as empty lists. This example shows each family configured:

{
  "data": {
    "type": "min-stay-customizations",
    "id": "123",
    "attributes": {
      "min-stay": 2,
      "gap-fill-min-stay": {"enabled": true, "gaps": 3, "buffer": 1},
      "seasonal-min-stays": [
        {"start-date": "2026-12-20", "end-date": "2027-01-05",
         "rollover": true, "min-stay": 5, "min-stay-locked": false}
      ],
      "last-minute-min-stays": [
        {"days-away": 7, "direction": "within", "min-stay": 1}
      ],
      "day-of-week-min-stays": [
        {"weekday": "monday", "min-stay": null},
        {"weekday": "tuesday", "min-stay": null},
        {"weekday": "wednesday", "min-stay": null},
        {"weekday": "thursday", "min-stay": null},
        {"weekday": "friday", "min-stay": 2},
        {"weekday": "saturday", "min-stay": 2},
        {"weekday": "sunday", "min-stay": null}
      ],
      "seasonal-day-of-week-min-stays": [
        {"start-date": "2026-08-28", "end-date": "2026-08-30",
         "min-stays": [
           {"weekday": "monday", "min-stay": null},
           {"weekday": "tuesday", "min-stay": null},
           {"weekday": "wednesday", "min-stay": null},
           {"weekday": "thursday", "min-stay": null},
           {"weekday": "friday", "min-stay": null},
           {"weekday": "saturday", "min-stay": null},
           {"weekday": "sunday", "min-stay": 2}
         ]}
      ],
      "seasonal-gap-fill-min-stays": [
        {"start-date": "2027-02-06", "end-date": "2027-02-13",
         "gap-fill-min-stay": {"enabled": true, "gaps": 1, "buffer": 2}}
      ],
      "seasonal-time-based-min-stays": [
        {"start-date": "2027-01-01", "end-date": "2027-01-22",
         "exclude": false,
         "time-based-min-stays": [
           {"days-away": 3, "direction": "within", "min-stay": 2}
         ]},
        {"start-date": "2027-04-01", "end-date": "2027-04-15",
         "exclude": true}
      ]
    }
  }
}

Annual Minimum Stay¶

Use min-stay to set the default minimum stay across all dates, except where a day-of-week or seasonal rule overrides it. 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¶

Use day-of-week-min-stays to set year-round minimum stays for specific weekdays. These values take precedence over the annual minimum stay. Days set to null inherit the annual minimum stay value.

Seasonal Minimum Stays By Day Of Week¶

Use seasonal-day-of-week-min-stays to set weekday minimum stays for a date range. Each entry carries a min-stays list with all seven weekdays; days set to null fall back to the lower-precedence rules. 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¶

Use seasonal-min-stays to create date-range specific rules for holidays, events, or other periods of predictable demand. Set rollover to true to repeat the rule every year, and min-stay-locked to true to protect the value from automatic changes. 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¶

Use last-minute-min-stays to set a minimum stay based on how far away a booking is from today. Each rule carries days-away, a direction (within for dates within that many days, after for dates at least that many days away), and the min-stay to require. These rules take precedence over seasonal minimum stays.

Seasonal Time-Based Minimum Stays¶

Use seasonal-time-based-min-stays to tailor lead-time rules to specific date ranges so minimum-night requirements can vary by season. Each entry lists its own rules under time-based-min-stays, using the same shape as last-minute-min-stays. Set exclude to true to turn lead-time rules off for the range; an excluding entry carries no time-based-min-stays list.

Gap Fill Minimum Stays¶

Gap-fill settings apply minimum-stay protections around short openings between bookings. Use gap-fill-min-stay for the year-round setting and seasonal-gap-fill-min-stays for date-range overrides; a seasonal entry wraps its own gap-fill-min-stay object. gaps is the longest opening, in nights, that triggers the rule, and buffer adds extra nights around the gap that still count toward the rule.

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. Prices are in the listing's currency.

A GET returns every rule family (empty lists when unconfigured):

{
  "data": {
    "type": "min-max-price-customizations",
    "id": "123",
    "attributes": {
      "min-price": 95,
      "max-price": null,
      "monthly-min-price": null,
      "day-of-week-min-prices": [
        {"weekday": "monday", "min-price": null},
        {"weekday": "tuesday", "min-price": null},
        {"weekday": "wednesday", "min-price": null},
        {"weekday": "thursday", "min-price": null},
        {"weekday": "friday", "min-price": 120},
        {"weekday": "saturday", "min-price": 120},
        {"weekday": "sunday", "min-price": null}
      ],
      "seasonal-day-of-week-min-prices": [],
      "seasonal-prices": [
        {"start-date": "2026-12-20", "end-date": "2027-01-05",
         "rollover": true, "min-price": 150, "max-price": null}
      ],
      "seasonal-monthly-prices": []
    }
  }
}

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.

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"},
      "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.

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.

Manual Overrides¶

Every other customization describes a rule Beyond applies while pricing. Use manual-overrides when you want to take over specific dates instead, the same way the Beyond web calendar's "Manual Override" panel does.

Each entry in overrides covers a date range and carries at most one of:

price: a fixed nightly price. Beyond stops repricing those dates and publishes exactly this amount until you remove the override. A fixed price is accepted even when it falls below the listing's minimum price — an explicit override outranks the floor.
percentage-adjustment: a percentage applied to Beyond's modeled price, where 10 means +10% and -10 means -10%. The price keeps moving with the model; the adjustment is applied after every other pricing factor.

The two are mutually exclusive on any given date: setting one clears the other. An entry with neither value clears both, returning the dates to fully modeled pricing.

Each entry accepts:

start-date / end-date: the range the override applies to. Use the same value for both to override a single date. Dates that have already passed in the listing's timezone are rejected.
days-of-week: optional. Restricts the override to the named weekdays within the range — for example, only Fridays and Saturdays. Omit it to cover every date in the range.

PATCH is additive: dates you do not mention keep whatever override they already had. To remove overrides, send an entry with no value for the dates you want cleared.

Reading overrides back¶

GET returns one entry per overridden date, with start-date equal to end-date, so a response body can be sent straight back as a request body. Dates with no override are omitted entirely.

Narrow the window with filter[start-date] and filter[end-date] (YYYY-MM-DD). The default window is today through today + 365 days in the listing's timezone.

GET /api/v1/listings/123/customizations/manual-overrides/?filter[start-date]=2026-06-01&filter[end-date]=2026-06-30

{
  "data": {
    "type": "manual-override-customizations",
    "id": "123",
    "attributes": {
      "overrides": [
        {"start-date": "2026-06-05", "end-date": "2026-06-05", "price": 250,
         "percentage-adjustment": null},
        {"start-date": "2026-06-06", "end-date": "2026-06-06", "price": null,
         "percentage-adjustment": 10}
      ]
    }
  }
}

To see which dates on the pricing calendar carry an override without fetching this resource, read price-override-type on the calendar entries.

Errors¶

All customization endpoints share the same error behavior. Writes are applied through Beyond's pricing engine, and its rejections are normalized into standard JSON:API error responses with the matching status code.

Status	Cause
`400`	Malformed body, a value failing field validation (e.g. `base-price` below `10`, missing weekdays in a day-of-week set, a backwards date range), or a rule the pricing engine rejects.
`401`	Missing or invalid bearer token.
`403`	Token lacks the required scope (`listings:read` for GET, `listings:write` for PATCH), or the credential has no edit access to the listing.
`404`	No listing with that id is visible to your application.
`422`	The update is semantically impossible for the listing — e.g. a manual override on a past date, or a feature the listing's managed account does not support.
`429`	Rate limit exceeded. See Rate Limiting.