---
updatedAt: 2026-06-10T06:33:06.000Z
agentTools:
  projectIndex: https://booking-api-docs.guesty.com/llms.txt
---

# Retrieve Accurate Stay Pricing (pilot)

How to retrieve the total price of a booking to provide guests with accurate final prices.

## Overview

<br />

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.

<br />

## Endpoint

<br />

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

<br />

| Method | URL                                       |
| :----- | :---------------------------------------- |
| GET    | <https://booking.guesty.com/api/listings> |

<br />

## Before you begin

<br />

You must include the following query parameters:

<br />

| Path Parameter | Details                                                                           | Example                                                         | Required |
| :------------- | :-------------------------------------------------------------------------------- | :-------------------------------------------------------------- | :------- |
| `fields`       | Specify the listing fields you require. They must include `totalPrice` and `_id`. | `fields=totalPrice _id address city title accommodates reviews` | true     |
| `checkIn`      | The check-in date in ISO format (YYYY-MM-DD).                                     | `2026-04-02`                                                    | true     |
| `checkOut`     | The check-out date in ISO format (YYYY-MM-DD).                                    | `2026-04-12`                                                    | true     |

<br />

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

<br />

## Retrieve listings with total pricing

<br />

Send a `GET /api/listings` request that includes:

* `fields` with `_id` and `totalPrice`
* `checkIn`
* `checkOut`

<br />

### Example request

<br />

```curl
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}'

```

<br />

### Example response

<br />

```json
{
  "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
    }
  }
}

```

<br />

## How total pricing is calculated

<br />

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.

<br />

## Pagination behavior

<br />

<Callout icon="📘" theme="info">
  **Pilot**

  Cursor pagination is a pilot function. To request is please contact your Account Manager or <Anchor label="Guesty API Support" target="_blank" href="https://help.guesty.com/hc/en-gb/articles/9370047984413-Contacting-Customer-Experience">Guesty API Support</Anchor>. If you are a Guesty Marketplace Partner, reach out to your partnership contact.
</Callout>

<br />

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.

<br />

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

```

<br />

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

<br />

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

```

<br />

## Filtering and sorting behavior

<br />

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.

<br />

## Troubleshooting

<br />

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 <Anchor label="contact" target="_blank" href="https://help.guesty.com/hc/en-gb/articles/9370047984413-Contacting-Customer-Experience">contact</Anchor> Guesty's Customer Experience Team.

<br />