Minimum Stays

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

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 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:

1. Seasonal Time-Based Minimum Stays
2. Time-Based Minimum Stays
3. Seasonal Minimum Stays
4. Day of Week Minimum Stays
5. 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",
         "rollover": false,
         "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": "2026-07-01", "end-date": "2026-07-31",
         "rollover": true,
         "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",
         "rollover": false, "exclude": false,
         "time-based-min-stays": [
           {"days-away": 3, "direction": "within", "min-stay": 2}
         ]},
        {"start-date": "2027-04-01", "end-date": "2027-04-15",
         "rollover": false, "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 on the same dates; a repeating range must be shorter than one year. Set 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.