---
title: "Get guest folio overview"
method: GET
path: "/guest-folio/overview"
tags: ["Guest Folio"]
---

# Get guest folio overview

`GET /guest-folio/overview`

## Request

- Base URL: `https://open-api.guesty.com/v1`
- URL: `https://open-api.guesty.com/v1/guest-folio/overview`
- Auth: API key in header `authorization`

Retrieves a financial overview for one or more reservations from the guest folio.

**Field selection**

You must specify at least one field to return via the `fields` query parameter. `reservationId` is always included in every result, even if not listed in `fields`. Use the exact enum values listed — any unrecognized field name results in a 400 error.

**Partial success**

If some reservation IDs are not found, the response still returns HTTP 200. Found records appear in `results`; missing IDs are listed in `notFound`.

**Bulk limit**

A maximum of **200 reservation IDs** can be submitted per request. For larger datasets, paginate by calling this endpoint in batches of up to 200. Parallel requests are supported and recommended when retrieving many reservations.

**Currency**

Unless the field name explicitly indicates another currency (e.g. `hostPayoutUsd`), monetary values are expressed in the reservation's native currency. Use the `currency` field to determine which currency applies.

**Example usage**

Fetch the host payout and total taxes for two reservations:
```
GET /v1/guest-folio/overview?reservationIds=64a1f2c3e4b0a1b2c3d4e5f6,64a1f2c3e4b0a1b2c3d4e5f7&fields=hostPayout,totalTaxes,currency
```

## Query parameters

- `reservationIds` string[], required
- `fields` string[], required

## Response `200`

Folio overview data for the requested reservations. Only the requested fields are returned per result. Reservation IDs that were not found are listed in `notFound`.

- object
  - `results` object[], required: List of folio overview objects for each reservation ID that was found. Each object contains only the fields that were requested via the `fields` query parameter, plus `reservationId` which is always included.
    - `reservationId` string, required: The reservation ID this folio belongs to. Always returned regardless of the fields requested.
    - `id` string: Internal folio document ID.
    - `groupReservationId` string, nullable: ID of the parent group reservation. Present only for reservations that are part of a multi-unit group booking.
    - `listingId` string: ID of the listing (property unit) this financial record belongs to.
    - `accountId` string: ID of the property manager account that owns this record.
    - `platform` string: Booking channel platform identifier.
    - `source` string: Source identifier for this reservation.
    - `currency` string: ISO 4217 currency code for all monetary values in this folio.
    - `createdAt` string, date-time: Timestamp when this folio record was created, in ISO 8601 format.
    - `updatedAt` string, date-time: Timestamp of the last update to this folio record, in ISO 8601 format.
    - `canceledAt` string, date-time, nullable: Timestamp when this folio was canceled, in ISO 8601 format. Null if the reservation has not been canceled.
    - `rawAccommodationFare` number: Raw accommodation fare received from the booking channel or calculated in guesty before any markup extraction, fee deductions or adjustments, including any inclusive taxes.
    - `accommodationFareNet` number: Net accommodation fare after all discounts, promotions, markups, extra-person fees, fee deductions, adjustments, and inclusive tax extractions have been applied.
    - `accommodationFareIncTax` number, nullable: Net accommodation fare including all taxes that apply to it. Null when line-item tax calculation is not enabled for the account or reservation.
    - `totalBundledFees` number: Total value of fees that have been bundled into the accommodation fare.
    - `rawCleaningFee` number: Raw cleaning fee amount received from the booking channel or calculated in guesty before adjustments, including any inclusive taxes.
    - `cleaningFeeIncTax` number, nullable: Cleaning fee including all taxes that apply to it. Null when line-item tax calculation is not enabled for the account or reservation.
    - `totalFees` number: Total additional fees on this reservation before taxes.
    - `totalFeesIncTax` number, nullable: Total additional fees including all taxes that apply to them. Null when line-item tax calculation is not enabled for the account or reservation.
    - `totalTaxes` number: Total tax amount on this reservation across all components.
    - `guestFeeBase` number: Base guest service fee before VAT, typically collected by the booking channel from the guest.
    - `guestFeeVat` number: VAT portion of the guest service fee.
    - `channelCommission` number: Channel commission pre-deducted or included in the host payout.
    - `channelCommissionTax` number: Tax amount applied on the channel commission.
    - `channelCommissionIncTax` number: Total channel commission including its tax.
    - `channelCommissionTaxType` string: Tax type applied to the channel commission (e.g. `PERCENT_EXCLUSIVE`). Indicates how the channel commission tax is calculated relative to the base commission.
    - `subTotalPrice` number: Accommodation fare plus all fees before taxes (gross subtotal).
    - `hostPayout` number: Final host payout in the reservation currency.
    - `hostPayoutUsd` number: Final host payout converted to USD at the time of booking.
    - `hostOriginalPayout` number, nullable: Host payout amount before any cancellation adjustment. Present only for canceled reservations.
    - `useAccountRevenueShare` boolean: Whether account-level revenue share settings override the listing-level configuration.
    - `netIncomeFormula` string: Formula key used to compute net income for this reservation.
    - `netIncome` number: Computed net income for the host or property manager.
    - `commissionFormula` string: Formula key used to compute the property manager commission.
    - `commission` number: Property manager commission amount.
    - `commissionTaxPercentage` number: Tax percentage applied to the property manager commission.
    - `commissionTax` number: Tax amount on the property manager commission.
    - `commissionIncTax` number: Property manager commission total including its tax.
    - `ownerRevenueFormula` string: Formula key used to compute the owner revenue.
    - `ownerRevenue` number: Owner revenue amount.
    - `perStayTotals` object[]: Financial totals broken down per stay segment. Relevant for mid-stay reservations where the guest switches between units. Each element covers a distinct stay period and contains the same financial fields as the top-level folio.
      - `rawAccommodationFare` number: Raw accommodation fare calculated in guesty for this stay segment.
      - `accommodationFareNet` number: Net accommodation fare for this stay segment after discounts, promotions, markups, extra-person fees, fee deductions, adjustments, and inclusive tax extractions have been applied.
      - `totalFees` number: Total additional fees for this stay segment.
      - `subTotalPrice` number: Accommodation fare plus all fees before taxes for this stay segment.
      - `hostPayout` number: Final host payout for this stay segment in the reservation currency.
      - `hostPayoutUsd` number: Final host payout for this stay segment converted to USD.
      - `totalTaxes` number: Total taxes for this stay segment.
      - `listingId` string: Listing ID associated with this stay segment.
      - `stayIndex` integer: Zero-based index identifying the position of this stay segment.
      - `netIncomeFormula` string: Formula key used to compute net income for this segment.
      - `netIncome` number: Net income for this stay segment.
      - `commissionFormula` string: Formula key for property manager commission calculation for this segment.
      - `commission` number: Property manager commission amount for this stay segment.
      - `commissionTaxPercentage` number: Tax percentage applied to property manager commission for this segment.
      - `commissionTax` number: Tax amount on the property manager commission for this stay segment.
      - `commissionIncTax` number: Property manager commission total including tax for this stay segment.
      - `ownerRevenueFormula` string: Formula key for owner revenue calculation for this segment.
      - `ownerRevenue` number: Owner revenue amount for this stay segment.
    - `originalPerStayTotals` object[]: Snapshot of per-stay financial totals captured before a cancellation was applied. Same structure as `perStayTotals`. Useful for auditing or refund calculations.
      - `rawAccommodationFare` number: Raw accommodation fare calculated in guesty for this stay segment.
      - `accommodationFareNet` number: Net accommodation fare for this stay segment after discounts, promotions, markups, extra-person fees, fee deductions, adjustments, and inclusive tax extractions have been applied.
      - `totalFees` number: Total additional fees for this stay segment.
      - `subTotalPrice` number: Accommodation fare plus all fees before taxes for this stay segment.
      - `hostPayout` number: Final host payout for this stay segment in the reservation currency.
      - `hostPayoutUsd` number: Final host payout for this stay segment converted to USD.
      - `totalTaxes` number: Total taxes for this stay segment.
      - `listingId` string: Listing ID associated with this stay segment.
      - `stayIndex` integer: Zero-based index identifying the position of this stay segment.
      - `netIncomeFormula` string: Formula key used to compute net income for this segment.
      - `netIncome` number: Net income for this stay segment.
      - `commissionFormula` string: Formula key for property manager commission calculation for this segment.
      - `commission` number: Property manager commission amount for this stay segment.
      - `commissionTaxPercentage` number: Tax percentage applied to property manager commission for this segment.
      - `commissionTax` number: Tax amount on the property manager commission for this stay segment.
      - `commissionIncTax` number: Property manager commission total including tax for this stay segment.
      - `ownerRevenueFormula` string: Formula key for owner revenue calculation for this segment.
      - `ownerRevenue` number: Owner revenue amount for this stay segment.
    - `bundledFees` object[]: List of fees that were bundled into the accommodation fare rather than exposed as separate line items. Each entry describes a single bundled fee — its name, type, original amount, applied amount, and how it scales. Individual sub-fields can be requested via dot notation: `bundledFees.title`, `bundledFees.appliedAmount`, etc.
      - `title` string: Display name of this bundled fee.
      - `type` string: Fee type code for this bundled fee.
      - `appliedAmount` number: The fee amount after bundling has been applied.
      - `originalAmount` number: The original percentage / fixed amount before bundling was applied.
      - `multiplier` string: Defines how this fee scales. Common values: PER_NIGHT, PER_GUEST, PER_STAY.
      - `targetFee` string: The fare component this fee percentage was calculated against.
      - `isPercentage` boolean: Whether this fee was computed as a percentage rather than a fixed amount.
    - `deductedFees` object[]: List of fees that were deducted from the accommodation fare. Each entry describes a single deducted fee — its name, type, and amount. Individual sub-fields can be requested via dot notation: `deductedFees.title`, `deductedFees.appliedAmount`, etc.
      - `title` string: Display name of this deducted fee.
      - `type` string: Fee type code for this deducted fee.
      - `appliedAmount` number: Amount deducted from the accommodation fare for this fee.
  - `notFound` string[], required: List of reservation IDs from the request that could not be found. Even if some IDs are not found, the request returns HTTP 200 with the found results and this list of missing IDs.

## Other responses

- `400`: The request is invalid. Common causes: missing or empty `reservationIds`, more than 200 reservation IDs submitted, missing or empty `fields`, or an unrecognized field name in `fields`.

## Changes

- **2026-11-03** `3122b8618183`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/guesty/apis/guesty-open-api/changes/guest-folio/overview/get.md)

---

[API](https://skmtc.dev/guesty/apis/guesty-open-api.md) - [All operations](https://skmtc.dev/guesty/apis/guesty-open-api/llms.txt) - [OpenAPI document](https://skmtc.dev/guesty/apis/guesty-open-api/revisions/3122b8618183?raw)