Reservations¶

Read the reservations of your listings: when each stay is, its status, what it earns, and which listing it belongs to.

Endpoint	Method	Scope	Token Tier	Description
`/api/v1/reservations/`	GET	`reservations:read`	Both	List the reservations of your listings, by check-in date

Try it out

Explore schemas and make live requests in the Swagger UI.

Which reservations are returned¶

Reservations are the ones Beyond syncs from your listings' channels and PMS, the same ones the Beyond calendar shows. A request reads every listing your token can see, or only the ones named in filter[listing], up to 100 at a time.

A listing connected through a PMS returns the reservations its PMS reports. The same stay is often also synced from a channel the PMS distributes to, such as Airbnb; that copy is left out, so each stay appears once.
A multi-unit listing (a PMS listing that groups several units) also returns the reservations of its units. Each one's listing is the unit's own listing, so it appears once even when you request both the multi-unit listing and the unit.
Any other listing returns the reservations of all its channels.

Every status is returned by default, so a stay that was canceled stays visible with status: canceled instead of disappearing.

Amounts are in the reservation's own currency, the one it was booked in, with no conversion. They are decimals in major units: 820.5 is 820.50.

List Reservations¶

Request¶

GET /api/v1/reservations/?filter[listing]=123,456&filter[start-date]=2026-11-01&filter[end-date]=2026-11-30&filter[status]=accepted

Parameter	Description
`filter[listing]`	Comma-separated listing ids, at most 100. Defaults to every listing your token can see. An id your token cannot see returns no reservations rather than an error.
`filter[start-date]`	Only stays that check out on or after this date (`YYYY-MM-DD`). Defaults to today (UTC), so past stays are left out unless you ask for them.
`filter[end-date]`	Only stays that check in on or before this date (`YYYY-MM-DD`). No limit by default. Must not be before `filter[start-date]`.
`filter[status]`	Comma-separated statuses to keep: `accepted`, `unconfirmed`, `canceled`. All three by default.
`page[number]`, `page[size]`	Standard pagination. Default page size 25, maximum 100. Reservations are ordered by `checkin-date`, then `id`.

Together, start-date and end-date return every stay that overlaps the window, including one that started before it or ends after it.

Pages are numbered, so a reservation added or moved while you page through can shift the rest by one: a row may appear on two pages or on none. Upsert by id, and page through again later to pick up what moved.

Response¶

{
  "data": [
    {
      "type": "reservations",
      "id": "48213377",
      "attributes": {
        "reference": "HMQ4X2ZK8A",
        "channel": "guesty",
        "channel-id": "64f1c0a9e2",
        "status": "accepted",
        "is-owner-stay": false,
        "booked-at": "2026-09-02T14:31:07Z",
        "canceled-at": null,
        "checkin-date": "2026-11-01",
        "checkout-date": "2026-11-05",
        "guests": 3,
        "currency": "USD",
        "rental-amount": 820.0,
        "adr": 205.0
      },
      "relationships": {
        "listing": {"data": {"type": "listings", "id": "123"}}
      }
    }
  ],
  "meta": {
    "pagination": {"page": 1, "pages": 1, "count": 1}
  }
}

Fields¶

Field	Description
`id`	Reservation identifier.
`reference`	Confirmation code the host sees in their PMS or on the channel, or `null` when the channel does not send one.
`channel`	Integration the reservation was synced from, the same value as the listing's `channel-listings[].channel`.
`channel-id`	The reservation's identifier on that channel or PMS. Use it to match the reservation with your own records.
`status`	`accepted` for a confirmed stay, `canceled` for a confirmed stay that was later canceled, `unconfirmed` for a pending request or inquiry.
`is-owner-stay`	`true` when the stay is an owner booking rather than a guest booking, or `null` when the channel does not say.
`booked-at`	When the reservation was accepted (UTC, ISO 8601).
`canceled-at`	When the reservation was canceled (UTC, ISO 8601). `null` unless `status` is `canceled`, and also `null` when the channel does not send it.
`checkin-date`	Arrival date, in the listing's local calendar.
`checkout-date`	Departure date, in the listing's local calendar. The last night is the day before.
`guests`	Number of guests, or `null` when the channel does not send it.
`currency`	ISO 4217 code of `rental-amount` and `adr`.
`rental-amount`	The stay's accommodation amount, the figure that compares with the nightly prices Beyond posts, in major units of `currency`. `null` when the channel does not send it.
`adr`	Average daily rate: `rental-amount` divided by the number of nights, in major units of `currency`, rounded down to the cent. When `rental-amount` is `null`, Beyond derives it from the reservation's other amounts.
`relationships.listing`	The listing the reservation belongs to. For a unit of a multi-unit listing, the unit's own listing.

Guest names, contact details, and messages are not returned.

Use cases¶

Keep a reservations mirror in sync. List your listings with GET /api/v1/listings/, then page through their reservations 100 listings at a time, with filter[start-date] set to today and no end date, and upsert by id. A cancellation shows up as a status change on a reservation you already have.
Report revenue and occupancy. Keep status: accepted stays, leave out is-owner-stay: true ones, and sum rental-amount or the nights between checkin-date and checkout-date per listing and month.
Track pace and lead time. Compare booked-at with checkin-date to see how far ahead guests book.

Errors¶

Status	Cause
`400`	A malformed date, an `end-date` before the `start-date`, an unknown status, a non-numeric or more than 100 `filter[listing]` ids, a `sort` parameter (the order is fixed, by check-in date), or an unknown query parameter.
`401`	Missing or invalid bearer token.
`403`	Token does not have the `reservations:read` scope.
`429`	Rate limit exceeded. See Rate Limiting.