Airbnb Booking Settings

Read and change how a listing takes bookings on Airbnb: Instant Book, check-in and check-out hours, cancellation policy, advance notice, preparation time, and how far ahead the calendar is bookable.

What this covers

• Turn Instant Book on or off, or restrict it to guests with a good track record.
• Set the check-in window and the check-out hour.
• Choose the cancellation policy, and offer a non-refundable rate at a discount.
• Require a minimum advance notice, and decide whether guests may still request to book inside it.
• Block turnover nights between two stays, and cap how far ahead the calendar is bookable.

Read the settings

This read is served entirely from Repull's stored copy of the listing's Airbnb settings, kept up to date by the sync that runs in the background. It never calls Airbnb while you wait, so it is fast — and the values can be behind what a host changed in the Airbnb app a minute ago. Every response carries a dataFreshness envelope that tells you whether to trust it; read it before you act on the values.

curl "https://api.repull.dev/v1/channels/airbnb/listings/4118/booking-settings" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response

{
  "data": {
    "bookingMode": "instant_book",
    "instantBook": {
      "enabled": true,
      "guestCategory": "experienced_guests_only",
      "requiresGoodTrackRecord": true
    },
    "checkIn": { "start": 15, "end": 21 },
    "checkOut": { "time": 11 },
    "advanceNotice": {
      "hours": 24,
      "sameDayBookingsAllowed": false,
      "allowRequestToBook": true
    },
    "preparationTime": { "nights": 1 },
    "bookingWindow": { "days": 365, "unlimited": false },
    "cancellation": {
      "shortStayPolicy": "moderate",
      "longStayPolicy": "long_term_policy_1",
      "nonRefundable": {
        "enabled": true,
        "discountPercent": 10,
        "priceFactor": 0.9
      }
    }
  },
  "dataFreshness": {
    "lastSyncedAt": "2026-09-18T04:12:09.000Z",
    "stale": false,
    "accounts": [
      {
        "accountId": "1772489413932732258",
        "accountName": "Pomello",
        "lastSyncedAt": "2026-09-18T04:12:09.000Z",
        "stale": false
      }
    ]
  }
}

Response fields

Data freshness

The same envelope every Airbnb read returns. lastSyncedAt is the last sync that actually landed data — an attempt that failed or was rate-limited never moves it. accounts[] gives the verdict per connected account; the top-level fields aggregate them, and fixUrl is the screen that resolves the problem.

• stale: true — every connected account is behind. Nothing in the response is current; a write is still accepted, but you are deciding from old values.
• stale: false with reason: "partial_account_staleness" — some accounts are current and some are not. Read accounts[] to see which.
• stale: false with no reason — everything is current.
• reason is one of host_disconnected_since_<iso>, host_disconnected, host_not_activated, sync_lag_>_24h, never_synced, or partial_account_staleness.

The write below is different: it goes to Airbnb directly and returns what Airbnb echoed back, so its response needs no freshness envelope.

Change the settings

Body

What gets refused

Each of these returns 422 invalid_params with field naming the part of the body at fault, and nothing is written.

• instantBook — requiresGoodTrackRecord on its own is refused. It selects which guests may Instant Book, so it needs enabled: true beside it or an explicit guestCategory. Contradictions are refused too: guestCategory: "off" with enabled: true asks for two different things at once.
• checkIn — start must be earlier than end, unless either one is FLEXIBLE.
• cancellation.nonRefundable — enabled: true requires a discountPercent; there is no default discount to fall back on. enabled: false means no discount at all, so a discountPercent alongside it is meaningless. Over 30 percent is below Airbnb's floor and is refused.
• advanceNotice — send hours, allowRequestToBook, or both. Whichever you omit keeps the value Airbnb currently holds.
• bookingWindow — send days or unlimited: true, never both. They are two answers to the same question.
• preparationTime.nights — 0, 1 or 2. Airbnb accepts no other value.

How the write is applied

Your body maps onto two things Airbnb keeps separately, and they are applied in order:

1. Booking settings — Instant Book, check-in and check-out, cancellation.
2. Stay rules — advance notice, preparation time, booking window.

Response

applied lists which of the two groups this call touched, and settings is the full settings object in the same shape the read returns — built from what Airbnb echoed back, not from what you sent, so it is what actually took effect.

{
  "data": {
    "applied": ["bookingSettings", "availabilityRules"],
    "settings": {
      "bookingMode": "request_to_book",
      "instantBook": { "enabled": false, "guestCategory": "off", "requiresGoodTrackRecord": false },
      "checkIn": { "start": 15, "end": 21 },
      "checkOut": { "time": 11 },
      "advanceNotice": { "hours": 24, "sameDayBookingsAllowed": false, "allowRequestToBook": true },
      "preparationTime": { "nights": 1 },
      "bookingWindow": { "days": null, "unlimited": true },
      "cancellation": {
        "shortStayPolicy": "moderate",
        "longStayPolicy": "long_term_policy_1",
        "nonRefundable": { "enabled": true, "discountPercent": 10, "priceFactor": 0.9 }
      }
    }
  }
}

Common changes

Read the current settings

Start here. The read is free of upstream calls, so there is no reason not to look before you write.

curl "https://api.repull.dev/v1/channels/airbnb/listings/4118/booking-settings" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Turn Instant Book off

Every booking now arrives as a request you approve. bookingMode flips to request_to_book in the response.

curl -X PUT "https://api.repull.dev/v1/channels/airbnb/listings/4118/booking-settings" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instantBook": {"enabled": false}}'

Restrict Instant Book to guests with a good track record

One field does it: guestCategory both switches Instant Book on and says who it is open to. Sending requiresGoodTrackRecord by itself would be refused.

curl -X PUT "https://api.repull.dev/v1/channels/airbnb/listings/4118/booking-settings" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instantBook": {"guestCategory": "experienced_guests_only"}}'

Offer a 10% non-refundable rate

Send the discount as a whole percent. Repull converts it to Airbnb's 0.9 price factor and returns both.

curl -X PUT "https://api.repull.dev/v1/channels/airbnb/listings/4118/booking-settings" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cancellation": {"nonRefundable": {"enabled": true, "discountPercent": 10}}}'

Require 24 hours notice and one turnover night

Both live in the stay rules, so this is one call and one merge. The listing's minimum and maximum nights are untouched.

curl -X PUT "https://api.repull.dev/v1/channels/airbnb/listings/4118/booking-settings" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advanceNotice": {"hours": 24}, "preparationTime": {"nights": 1}}'

Let guests book any date on the calendar

Send unlimited: true on its own — pairing it with days is refused, and the response comes back with days: null.

curl -X PUT "https://api.repull.dev/v1/channels/airbnb/listings/4118/booking-settings" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bookingWindow": {"unlimited": true}}'

What you cannot set here

Three settings you can see in the Airbnb host dashboard have no field on the booking-settings resource Airbnb exposes to partners. Repull cannot read them and cannot write them, and would rather say so than invent a field that quietly does nothing.

Sending preReservationMessage, automaticStayExtension or sameDayCutoff in a body returns 422 whose fix points at the row above, rather than a 200 that changed nothing.

Fields you read but never write

Four fields exist only to save you a calculation. They are computed from a setting you can write, so write that one instead:

• bookingMode — follows the Instant Book state. Write instantBook.
• instantBook.requiresGoodTrackRecord — follows guestCategory. Write that, or enabled beside it.
• advanceNotice.sameDayBookingsAllowed — hours === 0. Write advanceNotice.hours.
• cancellation.nonRefundable.priceFactor — Airbnb's form of the discount. Write discountPercent.

cancellation.longStayPolicy is writable, but its values are opaque Airbnb policy ids — Repull does not translate them, and passes through exactly what you send and exactly what Airbnb returns. Read the current value before you change it.

Errors

• 403 connection_reauth_required — Airbnb no longer accepts this connection for this listing. Retrying cannot succeed; reconnect Airbnb and make sure the listing is selected. See connection_reauth_required.
• 403 listing_inactive — the listing is inactive. Activate it, then retry. See listing_inactive.
• 404 not_found — no listing with that id in this workspace, or it has no Airbnb connection. See not_found.
• 422 invalid_params — the body is wrong: an unknown key, a value out of range, or one of the combinations under What gets refused. field names it. See invalid_params.
• 422 airbnb_rejected — the body was valid and Airbnb refused it anyway. message carries Airbnb's own reason; retrying the same body will not change it. See airbnb_rejected.
• 429 airbnb_rate_limited — Airbnb is throttling this account. Back off and retry. See airbnb_rate_limited.
• 502 airbnb_error — Airbnb failed. Retry with exponential backoff. See airbnb_error.

// 422 — requiresGoodTrackRecord cannot decide on its own
{
  "error": {
    "code": "invalid_params",
    "message": "requiresGoodTrackRecord selects which guests may Instant Book, so it needs enabled: true or an explicit guestCategory alongside it.",
    "field": "instantBook.requiresGoodTrackRecord",
    "docs_url": "https://repull.dev/docs/errors/invalid_params",
    "request_id": "req_01J5X7Y8Z9ABCDEF12345678"
  }
}