GUguesty
Guest Folio

Get guest folio overview

Changed on

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

Query parameters

reservationIdsstring[] required

Comma-separated reservation IDs (for example 64a1f2c3e4b0a1b2c3d4e5f6,64a1f2c3e4b0a1b2c3d4e5f7). Maximum 200 per request.

fieldsstring[] required

Comma-separated field names to include in the response (for example hostPayout,currency,totalTaxes). Must specify at least one. reservationId is always returned. Unrecognized values result in HTTP 400. Nested array fields (e.g. bundledFees, perStayTotals) must be requested using their leaf paths (e.g. bundledFees.title, perStayTotals.hostPayout) — the parent name alone is not a valid selection. For a description of each field, see the Response Body section on this page.

Response

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.

notFoundstring[] 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.

Example response

{
  "results": [
    {
      "reservationId": "64a1f2c3e4b0a1b2c3d4e5f6",
      "id": "64a1f2c3e4b0a1b2c3d4e5f0",
      "groupReservationId": "64a1f2c3e4b0a1b2c3d4e5ff",
      "listingId": "64a1f2c3e4b0a1b2c3d4e5fa",
      "accountId": "64a1f2c3e4b0a1b2c3d4e5fb",
      "platform": "airbnb2",
      "source": "manual",
      "currency": "USD",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-20T14:00:00.000Z",
      "canceledAt": "2024-01-25T09:00:00.000Z",
      "rawAccommodationFare": 500,
      "accommodationFareNet": 460,
      "accommodationFareIncTax": 510,
      "totalBundledFees": 40,
      "rawCleaningFee": 80,
      "cleaningFeeIncTax": 93.6,
      "totalFees": 120,
      "totalFeesIncTax": 136.2,
      "totalTaxes": 85,
      "guestFeeBase": 30,
      "guestFeeVat": 5.1,
      "channelCommission": 150,
      "channelCommissionTax": 25.5,
      "channelCommissionIncTax": 175.5,
      "channelCommissionTaxType": "PERCENT_EXCLUSIVE",
      "subTotalPrice": 580,
      "hostPayout": 590,
      "hostPayoutUsd": 590,
      "hostOriginalPayout": 600,
      "netIncomeFormula": "host_payout - commission",
      "netIncome": 531,
      "commissionFormula": "0.1 * host_payout",
      "commission": 59,
      "commissionTaxPercentage": 17,
      "commissionTax": 10.03,
      "commissionIncTax": 69.03,
      "ownerRevenueFormula": "host_payout - fare_accommodation",
      "ownerRevenue": 130,
      "perStayTotals": [
        {
          "rawAccommodationFare": 300,
          "accommodationFareNet": 285,
          "totalFees": 50,
          "subTotalPrice": 335,
          "hostPayout": 320,
          "hostPayoutUsd": 320,
          "totalTaxes": 35,
          "netIncomeFormula": "host_payout - commission",
          "netIncome": 288,
          "commissionFormula": "0.1 * host_payout",
          "commission": 32,
          "commissionTaxPercentage": 17,
          "commissionTax": 5.44,
          "commissionIncTax": 37.44,
          "ownerRevenueFormula": "host_payout - fare_accommodation",
          "ownerRevenue": 35
        }
      ],
      "originalPerStayTotals": [
        {
          "rawAccommodationFare": 300,
          "accommodationFareNet": 285,
          "totalFees": 50,
          "subTotalPrice": 335,
          "hostPayout": 320,
          "hostPayoutUsd": 320,
          "totalTaxes": 35,
          "netIncomeFormula": "host_payout - commission",
          "netIncome": 288,
          "commissionFormula": "0.1 * host_payout",
          "commission": 32,
          "commissionTaxPercentage": 17,
          "commissionTax": 5.44,
          "commissionIncTax": 37.44,
          "ownerRevenueFormula": "host_payout - fare_accommodation",
          "ownerRevenue": 35
        }
      ],
      "bundledFees": [
        {
          "title": "Resort Fee",
          "type": "RESORT_FEE",
          "appliedAmount": 25,
          "originalAmount": 30,
          "multiplier": "PER_NIGHT",
          "targetFee": "ACCOMMODATION_FARE"
        }
      ],
      "deductedFees": [
        {
          "title": "Management Fee",
          "type": "MANAGEMENT_FEE",
          "appliedAmount": 15
        }
      ]
    }
  ],
  "notFound": [
    "64a1f2c3e4b0a1b2c3d4e5f9"
  ]
}

Changes