---
title: "Search folio transactions"
method: POST
path: "/accounting/v1.0/folios/transactions"
tags: ["Folios"]
---

# Search folio transactions

`POST /accounting/v1.0/folios/transactions`

## Request

- Base URL: `https://api.cloudbeds.com`
- URL: `https://api.cloudbeds.com/accounting/v1.0/folios/transactions`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Implicit: `https://hotels.cloudbeds.com/api/v1.2/oauth`
    - Scopes: `read:payment`

Search and retrieve both posted and pending transactions for a source (reservation, group profile, or house account), merged into a single response. This endpoint uses POST (instead of GET) to support complex filter and grouping criteria in the request body. Results can be grouped by date, transaction type, folio, or other fields.

Results are always wrapped in groups. When groupBy is specified, transactions are grouped by that field. When omitted, all transactions are placed in a single group with key "default". Pagination is applied first (cursor-based on flat transactions), then grouping is applied to the page results. Groups at page boundaries may be partial.

When includeTotal is true, totals and foreign currency totals are computed on the first page and cached in Redis. Subsequent pages return cached totals. When no filters are applied, the total amount is read from the pre-computed source balance for optimal performance.

Supported filter fields: folioId, posted, descriptionFilters, transactionDate range, serviceDate range, subSourceIds, searchQuery.

Supported sort fields: transaction_datetime, service_date, id, internal_code.

Supported groupBy fields: transaction_date, service_date, internal_code_group, description, sub_source_identifier, folio_id, user_id.

## Headers

- `X-Property-ID` integer, required

## Request body

- ListFolioTransactionsRequest
  - `sourceId` integer, required: Numeric ID of the source entity: the numeric reservation ID for RESERVATION, the group profile ID for GROUP_PROFILE, or the house account ID for HOUSE_ACCOUNT. This is always a bigint — not the alphanumeric reservation identifier that some properties use (that value is exposed as `sourceIdentifier` on transactions).
  - `sourceKind` 'RESERVATION' | 'HOUSE_ACCOUNT' | 'GROUP_PROFILE' | 'ACCOUNTS_RECEIVABLE_LEDGER', required: The type of financial source that owns transactions and balances. RESERVATION is an individual guest booking, HOUSE_ACCOUNT is a property-level account for miscellaneous charges, GROUP_PROFILE is a group booking that can aggregate charges from multiple reservations, and ACCOUNTS_RECEIVABLE_LEDGER tracks balances transferred for later collection.
  - `folioId` integer: Filter by specific folio
  - `posted` boolean: Filter by posted status. Omit to include both posted and pending.
  - `descriptionFilters` string[]: Filter by transaction description identifiers. Accepts composite identifiers in the format: "{type}_{originId}" for item-level filtering (e.g. "product_123", "tax_456", "addon_789", "fee_101", "custom_item_202", "bookable_resource_303"), literal group names for room revenue ("rate", "roomRevenue_manual", "roomRevenue_cancellation", "roomRevenue_no_show", "accountsReceivable"), or payment method codes ("cash", "ebanking", "cards_visa", "cards_master", "pay_pal"). Server translates these to internalTransactionCode group + originId query conditions.
  - `transactionDateFrom` string, date-time: Filter transactions from this datetime (UTC, inclusive)
  - `transactionDateTo` string, date-time: Filter transactions to this datetime (UTC, inclusive)
  - `serviceDateFrom` string, date: Filter by service date from (inclusive)
  - `serviceDateTo` string, date: Filter by service date to (inclusive)
  - `subSourceIds` integer[]: Filter by sub-source IDs (booking room IDs for reservations)
  - `searchQuery` string: Free text search on transaction description
  - `groupBy` 'transaction_date' | 'service_date' | 'internal_code_group' | 'description' | 'sub_source_identifier' | 'folio_id' | 'user_id' | 'reservation_name' | 'room_name': Field to group transactions by. When omitted, all transactions are placed in a single group with key "default".
  - `sort` Sort[]
    - `field` string, required
    - `direction` 'asc' | 'desc', required: Direction for sort - asc or desc
  - `pageToken` string
  - `limit` integer: Page size. Default 100, max 1100.
  - `includeVoided` boolean: Include voided and routed-away transactions (the audit trail). When false, void transactions and the originals they voided are excluded (full chain removal via rootId matching), and so is every row a routing hop left behind on the requested source: the routed-away original and its offsetting routed (R) contra. Posted rows stay visible only on the source the chain currently lives on; pending rows only on their current (routed-to, else original) source.
  - `includeTotal` boolean: Include totals in response. On first page, totals are computed and cached in Redis. Subsequent pages return cached totals. When no filters are applied, total amount is read from the pre-computed source balance.

## Response `200`

OK

- ListFolioTransactionsPaginated
  - `groups` object: Ordered map of groupKey to group. Key is the string value of the groupBy field (e.g. "2026-02-25" for transaction_date). Pagination is applied first, then grouping.
  - `nextPageToken` string: Token for fetching the next page of results
  - `totals` FolioTransactionTotals: Global totals across all matching transactions (all pages).
    - `count` integer: Total number of matching transactions
    - `totalDebit` number, double: Net charges: signed sum of charge rows (room, items, taxes, fees, cancellation, no-show, gratuity), net of adjustments. May be negative. totalDebit - totalCredit equals the net balance of the rows in scope (differs from balanceDue by pending settlement, which balanceDue ignores).
    - `totalCredit` number, double: Net settlement: payments minus refunds/voids, plus AR transfers and channel commissions (AR transfers count as charges for ACCOUNTS_RECEIVABLE_LEDGER sources), including upcoming payments (positive) and upcoming refunds (negative). May be negative.
    - `currency` string: Property currency ISO code
    - `currencyScale` integer
  - `foreignCurrencyTotals` ForeignCurrencyTotals: Tender-currency breakdown of totals.totalCredit across all matching transactions (all pages). Foreign-tendered payments are reported in foreign units; the property-currency entry covers property-tendered payments, payments whose payment-service lookup could not resolve, AR transfers, and channel commissions. Entries are net (payments minus refunds/voids), negative when refunds exceed payments, omitted when the net is zero. Only present when at least one foreign-currency payment exists.
    - `debit` object: Always empty; refunds are netted into credit. Retained for response-shape compatibility.
    - `credit` object: Map of tender currency code to net amount (e.g. {"RON": 724.82, "EUR": 5})

## Other responses

- `400`: Bad Request

---

[API](https://skmtc.dev/cloudbeds/apis/accounting-api.md) - [All operations](https://skmtc.dev/cloudbeds/apis/accounting-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cloudbeds/apis/accounting-api/revisions/0b58c698deef?raw)