List the bookings of the Connection Scope

GET/api/v1/bookings

Requires bookings.read

Bookings of the Properties in the Connection Scope, cancelled ones included, ordered by id and paged with next_cursor. A page never repeats nor skips a booking, even while bookings change.

Without more Permissions a booking carries no guest name, email or phone and no amount: guests.read adds the guest block, prices.read adds the amounts block.

Incremental sync: read every page, keep next_updated_since, and pass it as updated_since next time. A change to a booking, its status, its amounts or its guest details brings it back. Poll without from/to, or a booking whose dates leave the range is never reported. A booking removed from ZenHost (for instance when a Sales Channel is disconnected from a Property, or a Property is deleted) is not reported, and sends no App Event: list the stay range again to reconcile. The booking.created, booking.updated and booking.cancelled App Events announce a change to what this endpoint returns, only to the connections that see it (a guest change needs guests.read, an amount change prices.read). A booking that arrives already cancelled sends only booking.created.

Request

curl -G https://app.zenhost.com/api/v1/bookings \
  -H "Authorization: Bearer zh_at_..." \
  -d "property_id[]=3f6c1a52-8d0e-4b7a-9f21-5c4e8b7d2a10" \
  -d "property_id[]=9b2e7d41-c3a8-4f65-8e1d-0a7f3c9b5e62"

const params = new URLSearchParams([
  ['property_id[]', '3f6c1a52-8d0e-4b7a-9f21-5c4e8b7d2a10'],
  ['property_id[]', '9b2e7d41-c3a8-4f65-8e1d-0a7f3c9b5e62'],
]);

const response = await fetch(`https://app.zenhost.com/api/v1/bookings?${params}`, {
  headers: {
    Authorization: 'Bearer zh_at_...',
  },
});
const data = await response.json();

import requests

response = requests.get(
    "https://app.zenhost.com/api/v1/bookings",
    params={"property_id[]": ["3f6c1a52-8d0e-4b7a-9f21-5c4e8b7d2a10", "9b2e7d41-c3a8-4f65-8e1d-0a7f3c9b5e62"]},
    headers={"Authorization": "Bearer zh_at_..."},
)
data = response.json()

Repeat property_id[] once per value, up to 100 per call.

Response

{
  "data": [
    {
      "id": "7d1e4c09-2b5a-4e83-a6f0-91c8d3b2e4f7",
      "property_id": "3f6c1a52-8d0e-4b7a-9f21-5c4e8b7d2a10",
      "status": "confirmed",
      "arrival_date": "2026-11-01",
      "departure_date": "2026-11-04",
      "sales_channel": {
        "code": "ABB",
        "name": "Airbnb"
      },
      "channel_reference": "HMABCD1234",
      "occupancy": {
        "adults": 2,
        "children": 0,
        "infants": 1
      },
      "created_at": "2026-10-10T08:00:00.000Z",
      "updated_at": "2026-10-10T08:00:00.000Z",
      "guest": {
        "first_name": "Camille",
        "last_name": "Martin",
        "email": "camille@example.com",
        "phone": "+33612345678"
      },
      "amounts": {
        "currency": "EUR",
        "total": 480,
        "commission": 72,
        "lines": [
          {
            "type": "nights",
            "label": "Nights",
            "amount": 480,
            "withheld_by_channel": false,
            "included_in_price": false
          }
        ]
      }
    }
  ],
  "next_cursor": null,
  "next_updated_since": "2026-10-10T08:00:00.000Z"
}

{
  "error": {
    "code": "unauthorized",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "subscription_blocked",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "app_suspended",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "property_out_of_scope",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "A human-readable explanation",
    "details": {}
  }
}

Parameters

Query parameters

property_id[]string (uuid)[]
Only these Properties (repeat the parameter, at most 100). Each must be in the Connection Scope. Leave it out to list the whole Connection Scope, page by page.
at most 100 items
fromstring (date)
Only stays with a night on or after this day (departure_date > from).
tostring (date)
Only stays with a night on or before this day (arrival_date <= to).
updated_sincestring (date-time)
Only bookings created or changed at or after this instant, cancellations included. Use next_updated_since of your previous listing.
cursorstring
next_cursor of the previous page.
limitinteger
Page size.
min 1 · max 500 · default 100

Responses

200One page of bookings.

application/jsonBookingList

dataBooking[]required
Show 12 child attributesHide child attributes
- idstring (uuid)required
- property_idstring (uuid)required
- statusstringrequired
  A cancelled booking stays listed with this status. Version 1 may add values.
  One of: confirmed cancelled
- arrival_datestring (date)required
  First night, YYYY-MM-DD in the property time zone.
- departure_datestring (date)required
  Check-out day (not a night), YYYY-MM-DD.
- sales_channelobjectrequired
  Where the booking was made.
  Show 2 child attributesHide child attributes
  codestringrequired
  direct (entered by the host), website (direct website), other, or the Sales Channel shortcode (e.g. ABB for Airbnb, BDC for Booking.com).
  namestringrequired
- channel_referencestring | nullrequired
  Confirmation code of the booking on its Sales Channel.
- occupancyobjectrequired
  Show 3 child attributesHide child attributes
  adultsinteger | nullrequired
  childreninteger | nullrequired
  infantsinteger | nullrequired
- created_atstring (date-time)required
  When the booking was made: on its Sales Channel, or in ZenHost for a direct booking. For a booking made before its Property was synchronized with ZenHost, when it was synchronized.
- updated_atstring (date-time)required
  Last change of the booking, its status, amounts or guest details.
- guestBookingGuest | null
  Show 4 child attributesHide child attributes
  first_namestring | nullrequired
  last_namestring | nullrequired
  emailstring | nullrequired
  phonestring | nullrequired
- amountsBookingAmounts
  Booking amounts. Present only with the prices.read Permission.
  Show 4 child attributesHide child attributes
  currencystringrequired
  ISO 4217 code of the amounts below.
  totalnumberrequired
  Sum of the lines not included in another line, in decimal units of currency.
  commissionnumberrequired
  Commission kept by the Sales Channel (0 when none is known, or when no line counts toward total).
  linesBookingAmountLine[]required
  The amount lines of the booking.
  Show 5 child attributesHide child attributes
  typestringrequired
  nights accommodation, discount (negative), cleaning, city_tax, tax another tax, linen, extra an extra service sold to the guest, fee another fee, other. Version 1 may add values.
  One of: nights discount cleaning city_tax tax linen extra fee other
  labelstringrequired
  Name of the line, as the Sales Channel or the host wrote it.
  amountnumberrequired
  Amount of the line, in currency.
  withheld_by_channelbooleanrequired
  Whether the Sales Channel withholds this amount from what it pays the host, such as a city tax Airbnb pays the city itself; the host never receives it.
  included_in_pricebooleanrequired
  Whether the amount is already part of another line's price, such as VAT or a fee the Sales Channel folded into the nights; it is then left out of total.
next_cursorstring | nullrequired
Pass it as cursor, with the same filters, to read the next page; null on the last page.
next_updated_sincestring (date-time)required
Once the last page is read, pass it as updated_since to receive every booking changed since this listing began. Some bookings may come again: upsert them by id.

401Error code: unauthorized, connection_revoked.

Error codes

unauthorized The access token is missing, unknown, expired or revoked, or was issued before the account connected the App again. Refresh it; if refreshing fails, ask the owner to connect again.
connection_revoked The owner revoked the App Connection (or your App revoked its own refresh token). Stop calling for this account and drop its tokens.

402Error code: subscription_blocked.

Error codes

subscription_blocked The ZenHost subscription of the account is blocked (unpaid, cancelled…). The connection is kept: tell your customer, calls work again once the subscription is restored.

403Error code: app_suspended, forbidden_permission.

Error codes

app_suspended ZenHost suspended your App, or no longer allows it on this account. Stop calling and contact ZenHost.
forbidden_permission Your App was not granted the Permission this endpoint requires.

422Error code: property_out_of_scope, validation_failed.

Error codes

property_out_of_scope A requested Property is outside the Connection Scope; details.property_ids lists them.
validation_failed The query, headers or body are invalid; details.issues points at each problem (path, message, and maximum when a value or list is too big).

429Error code: rate_limited.

Header Retry-After — Seconds to wait before the next call is allowed. Limits per App Connection: 60 reads (GET), 10 writes (other POST) and 30 messages sent to guests per minute.

Error codes

rate_limited Too many calls on this App Connection. Wait for the number of seconds in Retry-After.

500Error code: internal_error.

Error codes

internal_error ZenHost failed to answer. Retry later with a back-off.

Every error code and what to do