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
`/api/v1/listings/<id>/customizations/occupancy-based-pricing/`	GET	`listings:read`	Get occupancy-based pricing customization for a listing
`/api/v1/listings/<id>/customizations/occupancy-based-pricing/`	PATCH	`listings:write`	Update occupancy-based pricing customization for a listing
`/api/v1/listings/<id>/customizations/checkin-checkout-days/`	GET	`listings:read`	Get check-in/check-out days customization for a listing
`/api/v1/listings/<id>/customizations/checkin-checkout-days/`	PATCH	`listings:write`	Update check-in/check-out days customization for a listing
`/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.

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.
occupancy-based-pricing: fine-tuning from the listing's occupancy compared with its market, with optional caps and excluded date ranges.
checkin-checkout-days: the weekdays guests may check in and check out, year-round and per season.
gap-price-adjustments: discounts and premiums for the nights of short open gaps between bookings, either dynamic or manually configured.

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.
Every item of a seasonal list (seasonal-*) has a start-date, an end-date, and a rollover flag. Set rollover to true to repeat the season every year on the same dates; a repeating range must be shorter than one year, and its dates are reported in the current year. A seasonal list, when sent, replaces the listing's whole list, repeating seasons included, so the body of a GET can be sent back unchanged.

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
occupancy-based-pricing
checkin-checkout-days
gap-price-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
    }
  }
}

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 or a value failing validation. Examples: `base-price` below `10`, missing weekdays in a day-of-week set, a backwards date range, a `rollover` range of one year or more, a one-off range ending more than 5 years from today, a minimum price above the maximum, a manual override on a past date, or a range overlapping an earlier one in the same list. `source.pointer` names the list item, and the field when one is at fault.
`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. manual gap price adjustments while dynamic gap price adjustments are enabled, a feature the listing's managed account does not support, or check-in/check-out days the listing's channel does not accept (see `channel-support`).
`429`	Rate limit exceeded. See Rate Limiting.