Syncing Reservation Financials with an External Invoicing or Financial Reporting Solution
How to extract the guest invoice and payment information from a reservation.
Introduction
The reservation object contains all the monies paid to the host for the stay, the fee breakdown, and how much has been received. This document explains how to extract and map these fees for reconciliation with your external invoicing or financial reporting solution. It breaks down the data into the following categories:
Available Endpoints
You can retrieve multiple reservations per request or a single reservation. See the complete examples section for suggested uses.
Method | Endpoint | Description |
---|---|---|
GET | /reservations | Search reservation. Use it to retrieve a collection of reservations. |
GET | /reservations/{id} | Retrieve a single reservation. |
Basic Reservation Details
This section highlights the fields that will provide you with the basic details of the guest stay.
Key Parameters
Path Parameter | Description | Example |
---|---|---|
_id string | The primary key/identifier of the reservation. | “6602c364237d5e3771d9fffa” |
 
Body Parameter |
Description |
Example |
|
The primary key/identifier of the reservation. |
|
|
The secondary identifier of the reservation. |
|
|
The start date (YYYY-MM-DD) of the reservation according to the location of the property |
|
|
The check-out date (YYYY-MM-DD) of the reservation according to the location of the property |
|
|
The source of the booking. |
|
|
Identifying details about the property that was booked. |
"listing": { |
|
The total number of nights booked. |
|
|
The number of guests expected. |
|
|
The guest’s identifying details. |
"guest": { |
|
The date and time the booking was created in Guesty. |
|
|
The date and time the reservations was confirmed in Guesty. |
“2024-03-14T07:22:14.797Z” |
|
The date and time of the last action taken on the reservation. |
|
|
When a booking is canceled, include this to return the date on which it happened. |
|
Annotated Payload Excerpt
Reservation Financials
This section outlines the key parameters that will provide you with the guest invoice, payments, total payout, total collected, and balance due, as well as the tax definitions used to calculate the tax collected.
Key Parameters
Body Parameter |
Description |
Example |
|
Contains the definition of the taxes applied to the reservation. |
"atTimeOfConfirmation":{ |
|
An array of guest invoice objects. |
See the complete example that follows this table. |
|
The total payout. |
|
|
The total payout in USD. |
|
|
The total taxes collected. |
|
|
The amount paid by the guest/collected by the host. |
|
|
The amount due to be paid/collected. |
|
|
The commission taken by the booking channel. |
|
|
The tax paid on the commission. |
|
|
The channel commission paid inclusive of tax. |
|
You can retrieve more complete guest and property information by requesting each object from their respective endpoints.
Guest Invoice
The money.invoiceItems
array contains the invoice line items. Guesty assigns each fee a category according to the following fields:
type
normalType
secondIdentifier
(additional fees only)
Please refer to the following resources to reference and define each fee type:
Aggregate totals are provided through the fields: money.hostPayout
, money,totalPaid
, money.balanceDue
.
Annotated Payload Excerpt
Tax Definitions
Guesty supports many different types of taxes and definitions. To retrieve the tax definitions used to calculate the tax on a direct reservation, include atTimeOfConfirmation.taxes
and/or money.settingsSnapshot.taxes
in your request.
Each definition contains:
- The fees upon which a percentage-based tax is applied (
appliedOnFees
), - The tax
type
, - The
amount
, be it fixed or a percentage (indicated by the units field), and whether it is calculated per stay, per night, or per person per night, etc.
To learn more about Guesty's implementation of taxes, see our Help Center.
Annotated Payload Excerpt
Guest Payments
The following table lists the elements of the payment object that provide the basic details needed to recognize a payment, what was paid, when and whether it succeeded, failed, or is a future scheduled payment.
Key Parameters
 
Body Parameter |
Description |
Example |
|
The status of a payment. |
|
|
The primary identifier of a reservation payment object. |
|
|
The amount paid. |
|
|
The currency of the transaction. |
|
|
The date and time the payment was taken. |
|
Annotated Payload Excerpt
In our example, there are two payments: One that was scheduled for collection, indicated by the PENDING status, and one that was collected, indicated by the SUCCEEDED status. You can also see the date that the payment was scheduled for (shouldBePaidAt
) and the date on which it was collected (paidAt
).
A payment will appear nested under the chargebacksData
object if it is reversed.
Complete Payload Example
Single Reservation
Request
curl 'https://open-curl 'https://open-api.guesty.com/v1/reservations/65e62adbac3b7a0013f6c846?fields=money.invoiceItems%20money.hostPayout%20money.hostPayoutUsd%20money.totalTaxes%20money.totalPaid%20money.balanceDue%20money.hostServiceFee%20money.hostServiceFeeTax%20money.hostServiceFeeIncTax%20guest%20confirmationCode%20money.payments.status%20money.payments.paidAt%20money.payments.amount%20money.payments._id%20money.payments.currency%20atTimeOfConfirmation.taxes%20money.settingsSnapshot.taxes%20nightsCount%20checkInDateLocalized%20checkOutDateLocalized%20%20listing%20createdAt%20confirmedAt%20lastUpdatedAt%20guestsCount' \
--header 'Authorization: Bearer {accessToken}
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {accessToken}");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "manual"
};
fetch("https://open-curl https://open-api.guesty.com/v1/reservations/65e62adbac3b7a0013f6c846?fields=money.invoiceItems%20money.hostPayout%20money.hostPayoutUsd%20money.totalTaxes%20money.totalPaid%20money.balanceDue%20money.hostServiceFee%20money.hostServiceFeeTax%20money.hostServiceFeeIncTax%20guest%20confirmationCode%20money.payments.status%20money.payments.paidAt%20money.payments.amount%20money.payments._id%20money.payments.currency%20atTimeOfConfirmation.taxes%20money.settingsSnapshot.taxes%20nightsCount%20checkInDateLocalized%20checkOutDateLocalized%20%20listing%20createdAt%20confirmedAt%20lastUpdatedAt%20guestsCount \\ \n--header Authorization:", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://open-curl https//open-api.guesty.com/v1/reservations/65e62adbac3b7a0013f6c846?fields=money.invoiceItems%20money.hostPayout%20money.hostPayoutUsd%20money.totalTaxes%20money.totalPaid%20money.balanceDue%20money.hostServiceFee%20money.hostServiceFeeTax%20money.hostServiceFeeIncTax%20guest%20confirmationCode%20money.payments.status%20money.payments.paidAt%20money.payments.amount%20money.payments._id%20money.payments.currency%20atTimeOfConfirmation.taxes%20money.settingsSnapshot.taxes%20nightsCount%20checkInDateLocalized%20checkOutDateLocalized%20%20listing%20createdAt%20confirmedAt%20lastUpdatedAt%20guestsCount%20%5C%20%20%0A--header%20Authorization%3A',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer {accessToken}'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
import http.client
conn = http.client.HTTPSConnection("open-curl https")
payload = ''
headers = {
'Authorization': 'Bearer {accessToken}'
}
conn.request("GET", "//open-api.guesty.com/v1/reservations/65e62adbac3b7a0013f6c846?fields=money.invoiceItems%2520money.hostPayout%2520money.hostPayoutUsd%2520money.totalTaxes%2520money.totalPaid%2520money.balanceDue%2520money.hostServiceFee%2520money.hostServiceFeeTax%2520money.hostServiceFeeIncTax%2520guest%2520confirmationCode%2520money.payments.status%2520money.payments.paidAt%2520money.payments.amount%2520money.payments._id%2520money.payments.currency%2520atTimeOfConfirmation.taxes%2520money.settingsSnapshot.taxes%2520nightsCount%2520checkInDateLocalized%2520checkOutDateLocalized%2520%2520listing%2520createdAt%2520confirmedAt%2520lastUpdatedAt%2520guestsCount%20%5C%20%20%0A--header%20Authorization:", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Response
{
"_id":"65e62adbac3b7a0013f6c846",
"integration":{
"_id":"62e17d4270f77500329c613a",
"platform":"manual",
"limitations":{
"availableStatuses":[
]
}
},
"atTimeOfConfirmation":{
"taxes":[
{
"appliedOnFees":[
"AF",
"ADDITIONAL_BED",
"AIR_CONDITIONING",
"BABY_BED",
"CAR_RENTAL",
"CLEANING",
"CF",
"CLUB_CARD",
"COMMUNITY",
"CONCIERGE",
"CREDIT_CARD_PROCESSING_FEE",
"DAMAGE_WAIVER",
"DEPOSIT",
"EARLY_CHECK_IN",
"EARLY_CHECKOUT",
"ELECTRICITY",
"FOOD",
"HEATING",
"HOUSEKEEPING",
"INSURANCE",
"INTERNET",
"LATE_CHECK_IN",
"LATE_CHECKOUT",
"LAUNDRY",
"LINENS",
"MANAGEMENT",
"OIL",
"PARKING",
"PET",
"POOL",
"POOL_HEATING",
"RESORT",
"SERVICE",
"TOILETRIES",
"TOUR",
"TOWELS",
"TRANSFER",
"TRANSPORTATION",
"WATER",
"WOOD"
],
"appliedByDefaultOnChannels":[
],
"_id":"653a1f9678075351699f6275",
"type":"CITY_TAX",
"amount":5,
"units":"PERCENTAGE",
"quantifier":"PER_STAY",
"appliedToAllFees":true,
"isAppliedByDefault":false
}
]
},
"listingId":"64f03f9094d741004fda977d",
"checkInDateLocalized":"2024-03-20",
"checkOutDateLocalized":"2024-03-26",
"guestId":"63b439fae1d5a71d15345236",
"accountId":"62a8a2be2e53190032102a6e",
"guestsCount":2,
"money":{
"settingsSnapshot":{
"taxes":[
{
"appliedOnFees":[
"AF",
"ADDITIONAL_BED",
"AIR_CONDITIONING",
"BABY_BED",
"CAR_RENTAL",
"CLEANING",
"CF",
"CLUB_CARD",
"COMMUNITY",
"CONCIERGE",
"CREDIT_CARD_PROCESSING_FEE",
"DAMAGE_WAIVER",
"DEPOSIT",
"EARLY_CHECK_IN",
"EARLY_CHECKOUT",
"ELECTRICITY",
"FOOD",
"HEATING",
"HOUSEKEEPING",
"INSURANCE",
"INTERNET",
"LATE_CHECK_IN",
"LATE_CHECKOUT",
"LAUNDRY",
"LINENS",
"MANAGEMENT",
"OIL",
"PARKING",
"PET",
"POOL",
"POOL_HEATING",
"RESORT",
"SERVICE",
"TOILETRIES",
"TOUR",
"TOWELS",
"TRANSFER",
"TRANSPORTATION",
"WATER",
"WOOD"
],
"appliedByDefaultOnChannels":[
],
"_id":"653a1f9678075351699f6275",
"type":"CITY_TAX",
"amount":5,
"units":"PERCENTAGE",
"quantifier":"PER_STAY",
"appliedToAllFees":true,
"isAppliedByDefault":false
}
]
},
"invoiceItems":[
{
"_id":"65e62adc43b186000e76b45a",
"title":"Accommodation fare",
"amount":1446,
"currency":"USD",
"type":"ACCOMMODATION_FARE",
"isLocked":true,
"normalType":"AF",
"refId":"4ec1da31-7be0-4b83-9ede-8a28ec031b36"
},
{
"_id":"65e62adc43b186000e76b45b",
"title":"Damage Waiver",
"currency":"USD",
"isLocked":true,
"isAutoAdditionalFee":true,
"type":"ADDITIONAL",
"normalType":"AFE",
"secondIdentifier":"DAMAGE_WAIVER",
"amount":50,
"refId":"4245d338-0f78-4bf9-a564-143acaf3a315",
"baseAmount":50
},
{
"_id":"65e62adc43b186000e76b45c",
"title":"Early check in",
"currency":"USD",
"isLocked":true,
"isAutoAdditionalFee":true,
"type":"ADDITIONAL",
"normalType":"AFE",
"secondIdentifier":"EARLY_CHECK_IN",
"amount":60,
"refId":"76d6a071-fb72-4160-8f3b-7e36b541dfd8",
"baseAmount":60
},
{
"_id":"65e62adc43b186000e76b45d",
"title":"Pet fee",
"currency":"USD",
"isLocked":true,
"isAutoAdditionalFee":true,
"type":"ADDITIONAL",
"normalType":"AFE",
"secondIdentifier":"PET",
"amount":1000,
"refId":"31cedd0a-9449-4529-8df4-fb3584cfc09b",
"baseAmount":1000
},
{
"_id":"65e62adc43b186000e76b45e",
"title":"Resort Fee",
"currency":"USD",
"isLocked":true,
"isAutoAdditionalFee":true,
"type":"ADDITIONAL",
"normalType":"AFE",
"secondIdentifier":"RESORT",
"amount":100,
"refId":"e8f02376-7b9d-42bb-a412-bb21314d9f06",
"baseAmount":100
},
{
"_id":"6603e4a3926e68000e80f499",
"title":"CITY_TAX",
"amount":0.01,
"currency":"USD",
"isLocked":true,
"isTax":true,
"type":"TAX",
"metadata":{
"calculated":true
},
"normalType":"CT",
"refId":"1b91fd59-0967-4346-9323-a1c77bfab82e",
"baseAmount":132.8
}
],
"payments":[
{
"status":"PENDING",
"_id":"65f2a5a6235df60012574af7",
"chargebacksData":{
"chargebacks":[
]
},
"shouldBePaidAt":"2024-03-14T07:22:14.797Z",
"currency":"USD",
"amount":796.8
},
{
"status":"SUCCEEDED",
"_id":"65f2a5a6235df60012574af8",
"chargebacksData":{
"chargebacks":[
]
},
"shouldBePaidAt":"2024-03-27T09:19:19.000Z",
"currency":"USD",
"amount":1859.21,
"paidAt":"2024-03-27T09:19:19.000Z"
}
],
"currency":"USD",
"hostServiceFee":0,
"hostServiceFeeTax":0,
"hostServiceFeeIncTax":0,
"hostPayout":2656.01,
"hostPayoutUsd":2656.01,
"totalTaxes":0.01,
"balanceDue":796.8,
"totalPaid":1859.21
},
"confirmationCode":"LZBp1GKnW",
"nightsCount":6,
"createdAt":"2024-03-04T20:11:09.042Z",
"lastUpdatedAt":"2024-03-27T09:19:31.935Z",
"guest":{
"_id":"63b439fae1d5a71d15345236",
"hometown":"Cincinatti",
"fullName":"Steve Winward",
"lastName":"Winward",
"firstName":"Steve",
"email":"[email protected]",
"phone":"12015552369"
},
"listing":{
"_id":"64f03f9094d741004fda977d",
"prices":{
"currency":"USD"
},
"type":"SINGLE",
"title":"API Docs Test2",
"nickname":"API Docs2",
"address":{
"full":"Shlomo Ibn Gabirol St 69, Tel Aviv-Yafo, Israel"
},
"timezone":"Asia/Jerusalem",
"picture":{
"thumbnail":"https://assets.guesty.com/image/upload/c_fit,h_200/v1697532077/production/62a8a2be2e53190032102a6e/buufzhme6pnzgzzyndfp.jpg"
}
},
"confirmedAt":"2024-03-14T07:22:14.797Z"
}
Multiple Reservations
You can use the same field selection as in the previous example. Implement pagination and be sure to sort by the createdAt
date to ensure you retrieve all the reservations in the collection.
Request
curl 'https://open-api.guesty.com/v1/reservations?fields=money.invoiceItems%20money.hostPayout%20money.hostPayoutUsd%20money.totalTaxes%20money.totalPaid%20money.balanceDue%20money.hostServiceFee%20money.hostServiceFeeTax%20money.hostServiceFeeIncTax%20guest%20confirmationCode%20money.payments.status%20money.payments.paidAt%20money.payments.amount%20money.payments._id%20money.payments.currency%20atTimeOfConfirmation.taxes%20money.settingsSnapshot.taxes%20nightsCount%20checkInDateLocalized%20checkOutDateLocalized%20%20listing%20createdAt%20confirmedAt%20lastUpdatedAt%20guestsCount&skip=0&limit=25&sort=-createdAt' \
--header 'Authorization: Bearer {accessToken}
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {accessToken}");
myHeaders.append("Cookie", "JSESSIONID=4D54B67DEEB391EFC3520B0D393F7E4A");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "manual"
};
fetch("https://open-api.guesty.com/v1/reservations?fields=money.invoiceItems%20money.hostPayout%20money.hostPayoutUsd%20money.totalTaxes%20money.totalPaid%20money.balanceDue%20money.hostServiceFee%20money.hostServiceFeeTax%20money.hostServiceFeeIncTax%20guest%20confirmationCode%20money.payments.status%20money.payments.paidAt%20money.payments.amount%20money.payments._id%20money.payments.currency%20atTimeOfConfirmation.taxes%20money.settingsSnapshot.taxes%20nightsCount%20checkInDateLocalized%20checkOutDateLocalized%20%20listing%20createdAt%20confirmedAt%20lastUpdatedAt%20guestsCount&skip=0&limit=25&sort=-createdAt", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://open-api.guesty.com/v1/reservations?fields=money.invoiceItems%20money.hostPayout%20money.hostPayoutUsd%20money.totalTaxes%20money.totalPaid%20money.balanceDue%20money.hostServiceFee%20money.hostServiceFeeTax%20money.hostServiceFeeIncTax%20guest%20confirmationCode%20money.payments.status%20money.payments.paidAt%20money.payments.amount%20money.payments._id%20money.payments.currency%20atTimeOfConfirmation.taxes%20money.settingsSnapshot.taxes%20nightsCount%20checkInDateLocalized%20checkOutDateLocalized%20%20listing%20createdAt%20confirmedAt%20lastUpdatedAt%20guestsCount&skip=0&limit=25&sort=-createdAt',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer {accessToken}',
'Cookie: JSESSIONID=4D54B67DEEB391EFC3520B0D393F7E4A'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
import http.client
conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = ''
headers = {
'Authorization': 'Bearer {accessToken}',
'Cookie': 'JSESSIONID=4D54B67DEEB391EFC3520B0D393F7E4A'
}
conn.request("GET", "/v1/reservations?fields=money.invoiceItems%2520money.hostPayout%2520money.hostPayoutUsd%2520money.totalTaxes%2520money.totalPaid%2520money.balanceDue%2520money.hostServiceFee%2520money.hostServiceFeeTax%2520money.hostServiceFeeIncTax%2520guest%2520confirmationCode%2520money.payments.status%2520money.payments.paidAt%2520money.payments.amount%2520money.payments._id%2520money.payments.currency%2520atTimeOfConfirmation.taxes%2520money.settingsSnapshot.taxes%2520nightsCount%2520checkInDateLocalized%2520checkOutDateLocalized%2520%2520listing%2520createdAt%2520confirmedAt%2520lastUpdatedAt%2520guestsCount&skip=0&limit=25&sort=-createdAt", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
To restrict the response to confirmed reservations within a specific month, you can add a filter query, such as:
filters=[{"operator": "$between", "field": "checkOutDateLocalized", "context": "now", "from": "2024-02-01", "to":"2024-02-29"}, {"operator": "$eq", "field": "status", "value": "confirmed"}]
Reservation Price Adjustments
At Reservation Creation
When making direct reservations through your Guesty dashboard or the Open API, you can specify custom fees that override the property and rate plan defaults.
Booking channel reservations will use the rate plans and taxes set up on their extranet. Some information will be synced from Guesty, while others may only be found on the channel. For more information, please visit our Help Center.
After Reservation Creation
After creating the reservation, you can adjust or discount the accommodation fare and add an invoice item. For non-editable fees such as taxes, contact Customer Experience for assistance.
Webhooks
Subscribe to Guesty's reservation and payment webhooks to receive proactive notification upon receipt of new reservations, alterations to existing ones, and failed payments.
Updated 4 months ago