Financial webhooks

Overview

Keep track of your reservation financials by subscribing to Guesty's guest folio events. You'll receive a webhook whenever a reservation is created or the guest folio is updated, so you always have the latest financial information at your fingertips.

What notifications can I receive?

Below, you'll find the financial events you can subscribe to. Try out the events that work best for your workflow, and adjust your subscriptions as your business needs change. For step-by-step instructions, see how to subscribe to webhooks here.

Event	Description
`guest-folio.created`	Emitted when a reservation is created. It will provide a snapshot of the initial guest folio.
`guest-folio.updated`	Emitted when the guest folio is altered.

What can I expect?

Guest folio event payloads use the same structure as our guest folio API endpoints:

Get guest folio overview: top-level totals and timestamps
Get invoice items: each object in invoiceItems
Monetary amounts are in the reservation’s native currency (ISO 4217).
Dates are ISO strings:
createdAt / updatedAt as date-time—yyyy-mm-ddThh:mm:ss.sssZ
nightsBreakdown.date as YYYY-MM-DD
Fields with no stored value are omitted.
Nested arrays only include the leaf fields listed in the tables below.
adjustments.nightsBreakdown is excluded from the payload.

Debouncing, asynchronous sending, and data refresh

Guesty groups guest folio updates that happen within 30 seconds, so you only receive the most up-to-date information once changes are complete. This helps prevent unnecessary notifications while updates are still in progress.

Sometimes, events may arrive out of order. For example, you might receive the guest-folio.created event before the reservation.created.v2 event.

Updates from booking channels or other reservation details can refresh the guest folio and trigger a guest-folio.updated event, even if the folio itself hasn't changed.

You can find advice on handling the events in our Subscribe to webhooks guide.

Top-level parameters

The reservationId is always included. Other overview fields appear only when they have data.

Field	Details
`reservationId`	Reservation this folio belongs to. Always returned.
`currency`	ISO 4217 code for all monetary values.
`createdAt`	Folio created (ISO 8601).
`updatedAt`	Last folio update (ISO 8601). Use with reservationId to dedupe / ignore stale deliveries.
`totalFees`	Additional fees before taxes.
`totalFeesIncTax`	Additional fees including taxes. Omitted when line-item tax calculation is not enabled.
`totalTaxes`	Total tax across all components.
`guestFeeBase`	Guest service fee before VAT.
`guestFeeVat`	VAT on the guest service fee.
`channelCommission`	Channel commission in the host payout.
`channelCommissionTax`	Tax on channel commission.
`channelCommissionIncTax`	Channel commission including tax.
`subTotalPrice`	Accommodation fare plus fees, before taxes.
`hostPayout`	Final host payout in reservation currency.

Not in the webhook (available only on Get guest folio overview): listing/account metadata, accommodation-fare breakdowns, PM commission / net income / owner revenue, perStayTotals, bundledFees, deductedFees, hostPayoutUsd, etc.

`invoiceItems` array parameters

The invoice item id is always included. Other fields appear only when they have data for that item. The nightsBreakdown may be missing for flat fees, and adjustments may be missing or empty. For full details, use the Get invoice items endpoint.

Field	Meaning (see invoice items Response Body)
`id`	Invoice item ID. Always returned.
`normalType`	Line-item type (AF, CF, AFE, …).
`title`	Display name on the folio.
`secondIdentifier`	Sub-type when the item has variants (e.g. AFE + PARKING).
`totalPrice`	Final amount after adjustments.
`nightsSubtotal`	Nightly amounts before adjustments.
`isDeducted`	Deducted from accommodation fare.
`isDeductedV2`	Same, under v2 deduction logic.
`stayIndex`	Zero-based stay segment (mid-stay / unit change).
`nightsBreakdown[].date`	Night date (YYYY-MM-DD).
`nightsBreakdown[].basePrice`	Base price for that night.
`adjustments[].amount`	Adjustment amount (negative = reduction).
`adjustments[].type`	TOTAL_AMOUNT or NIGHTLY_RATE.
`adjustments[].userName`	Who created the adjustment.
`adjustments[].createdAt`	When it was created (ISO 8601).
`adjustments[].description`	Reason / label.

The following fields are not included in the payload: origin, description (item-level), listingId, realizationDates, markupBreakdown, logs, adjustments.creationMethod, and adjustments.nightsBreakdown. reservationId and currency only appear at the top level, not inside invoiceItems.

Response shape example

Both events use this same structure. The payload always shows the latest folio state at the time it is sent, not just the change that triggered the event.

{
  "reservationId": "64a1f2c3e4b0a1b2c3d4e5f6",
  "currency": "USD",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-20T14:00:00.000Z",
  "totalFees": 120,
  "totalFeesIncTax": 136.2,
  "totalTaxes": 85,
  "guestFeeBase": 30,
  "guestFeeVat": 5.1,
  "channelCommission": 150,
  "channelCommissionTax": 25.5,
  "channelCommissionIncTax": 175.5,
  "subTotalPrice": 580,
  "hostPayout": 590,
  "invoiceItems": [
    {
      "id": "64b2g3d4f5c1b2a3e4d5f6a7",
      "normalType": "AF",
      "title": "Accommodation fare",
      "totalPrice": 600,
      "nightsSubtotal": 650,
      "isDeducted": false,
      "isDeductedV2": false,
      "stayIndex": 0,
      "nightsBreakdown": [{ "date": "2024-06-15", "basePrice": 120 }],
      "adjustments": [
        {
          "amount": -50,
          "type": "TOTAL_AMOUNT",
          "userName": "[email protected]",
          "createdAt": "2024-06-10T09:00:00.000Z",
          "description": "Long-stay discount"
        }
      ]
    }
  ]
}