Retrieve Accurate Stay Pricing (pilot)

Overview

Use the Booking Engine API to return the total stay price for listings in search results.

The totalPrice field returns the estimated full cost of the stay, including the base rate, required fees, taxes, cleaning fees, and other mandatory charges. The value represents the lowest available rate plan price. Use it when you want guests to see the final price earlier in the booking flow.

Endpoint

The total price feature builds on the existing listings search endpoint.

Before you begin

You must include the following query parameters:

You can also include supported listing filters, such as occupancy, bedrooms, and bathrooms, as well as pagination parameters.

Retrieve listings with total pricing

Send a GET /api/listings request that includes:

• fields with _id and totalPrice
• checkIn
• checkOut

Example request

curl --location 'https://booking.guesty.com/api/listings?minOccupancy=5&numberOfBedrooms=4&numberOfBathrooms=2&fields=_id%20address.city%20title%20accommodates%20reviews%20totalPrice&checkIn=2026-04-02&checkOut=2026-04-09&limit=20' \
--header 'accept: application/json; charset=utf-8' \
--header 'Authorization: Bearer {token}'

Example response

{
  "results": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "title": "Beautiful Beach House",
      "accommodates": 6,
      "totalPrice": 1250.50
    },
    {
      "_id": "507f1f77bcf86cd799439012",
      "title": "Downtown Apartment",
      "accommodates": 4,
      "totalPrice": 850.00
    }
  ],
  "pagination": {
    "total": 2,
    "cursor": {
      "next": null
    }
  }
}

How total pricing is calculated

For each listing, Guesty calculates the final price for all available rates and returns the lowest available rate plan price as totalPrice. The value is returned in the property’s local currency.

Pagination behavior

📘

Pilot

Cursor pagination is a pilot function. To request is please contact your Account Manager or Guesty API Support. If you are a Guesty Marketplace Partner, reach out to your partnership contact.

When you request totalPrice, the API returns up to 50 listings per page. If the response includes a pagination.cursor.next value, use it to request the next page.

{
  "results": [...],
  "pagination": {
    "total": ...,
    "cursor": {
      "next": "eyJuZXh0Q3Vyc29yIjp7Imxpc..."
    }
  }
}

If pagination.cursor.next is null, there are no more pages.

{
  "results": [...],
  "pagination": {
    "total": ...,
    "cursor": {
      "next": null
    }
  }
}

Filtering and sorting behavior

You can use listing filters and price sorting when requesting totalPrice.

Keep the following behavior in mind:

• Price filters also apply to totalPrice.
• Price sorting first sorts listings by listing.basePrice, then by totalPrice.
• When sorting by price, the response may include fewer than 50 listings.

Troubleshooting

If totalPrice is missing, check that your request includes:

• totalPrice in the fields parameter
• _id in the fields parameter
• A valid checkIn date
• A valid checkOut date
• A valid authorization token

If you are unable to retrieve the totalPrice, or if you believe the final price calculation is incorrect, please contact Guesty's Customer Experience Team.