Payouts Reconciliation API Reference

The Payouts Reconciliation API retrieves payout data from Guesty Pay providers. It supports filtering by date range, payout ID, reservation confirmation code, and payment processor sub-accounts.

Core Concepts

Term	Definition
Sub-account ID	Payment processor sub-account in the format, `accountId.subAccountId` (e.g. `1234.1`).
Payout ID	Unique identifier of a payout generated by the payment processor.
Reservation	Booking associated with payout transactions, identified by, `reservationConfirmationCode`.

API Usage and Policies

The endpoint requires:

Authentication: Valid credentials for the Open API or Partners API
Payment Provider Configuration: Your account should have (active) Guesty Pay providers with payouts processed.

Endpoint Paths

Method	Path
GET	/payment-transactions/reports/payouts-reconciliation

Key Query Parameters

Parameter	Description	Required
`startDate`	Start date in ISO 8601 format (YYYY-MM-DD).	Yes
`endDate`	End date in ISO 8601 format (YYYY-MM-DD). The date must be on or after the start date.	Yes
`subAccountId`	Optional sub-account filter, format: `accountId.subAccountId` (numeric `number.number`).
`payoutId`	Optional payout ID to narrow results within the date range.
`reservationConfirmationCode`	Reservation confirmation code.
`skip`	Items to skip for pagination (default `0`).
`take`	Page size (default `25`, max `100`).

Things to note

Date range requirement: The startDate and endDate must be provided.
Date range length: Maximum consecutive date range is 31 days
Date ordering: endDate must be on or after startDate
Pagination: take must be between 1 and 100
Sub-account format: subAccountId must be number.number (e.g. 1234.1)

Sample request template

curl --location 'https://open-api.guesty.com/v1/payment-transactions/reports/payouts-reconciliation?startDate=YYY-MM-DD&endDate=YYYY-MM-DD&reservationConfirmationCode={confirmationCode}&subAccountId={subAccount}&skip=0&take=25' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {token}'

You can find the response schema on the reference document.

Common Error Scenarios

Scenario	HTTP Status	Error Message
Missing both the date range and the reservation code	`400`	`Date range is required`
Invalid date format	`400`	`Invalid date format`
Date range exceeds 31 days	`400`	`Date range cannot exceed 1 month`
End date before start date	`400`	`End date cannot be before start date`
Invalid `subAccountId` format	`400`	`subAccountId must be in the format number.number`
Unauthenticated request	`401`	`You need to be authenticated to access this endpoint`