Skip to content

Occupancy-Based Pricing

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

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.

When enabled, occupancy-based pricing fine-tunes the listing's prices with discounts and premiums based on its occupancy compared with its market. It is separate from the tier of dynamic time-based adjustments, which steers lead-time rules only.

The payload includes:

  • enabled: whether occupancy-based pricing is applied. The other fields take effect only while it is true; while it is false they are still saved and apply once it is turned back on.
  • tier: the strategy for its discounts and premiums. occupancy favors deeper discounts and lighter premiums, rate favors lighter discounts and stronger premiums, and revenue balances both.
  • min-factor: the largest decrease it may apply, as a fraction between -1 and 0 with up to four decimal places. -0.05 caps decreases at 5%, 0 blocks decreases, and null means no cap.
  • max-factor: the largest increase it may apply, as a fraction between 0 and 1 with up to four decimal places. 0.1 caps increases at 10%, 0 blocks increases, and null means no cap.
  • disabled-periods: up to 50 non-overlapping date ranges during which occupancy-based pricing is skipped, such as holidays, local events, or owner stays. end-date is the last skipped date; use the same value for both dates to skip a single date.

Today occupancy-based pricing adjusts a price by at most about 20% in either direction, so a min-factor or max-factor wider than that has no effect.

{
  "data": {
    "type": "occupancy-based-pricing-customizations",
    "id": "123",
    "attributes": {
      "enabled": true,
      "tier": "revenue",
      "min-factor": -0.05,
      "max-factor": 0.1,
      "disabled-periods": [
        {"start-date": "2026-12-24", "end-date": "2026-12-26"}
      ]
    }
  }
}

PATCH changes only the fields you send. disabled-periods, when sent, replaces the listing's whole list: include every period you want to keep, or send [] to remove them all. A request with overlapping periods is rejected with 400 and changes nothing.