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

# Search folio transactions

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

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 — Source ID (reservation ID, group profile ID, house account ID)
  - `sourceKind` 'GROUP_PROFILE' | 'RESERVATION' | 'HOUSE_ACCOUNT' | 'ACCOUNTS_RECEIVABLE_LEDGER', required — Kind of the source entity
  - `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 transactions. When false, both void transactions and the original transactions they voided are excluded (full chain removal via rootId matching).
  - `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 — Sum of all debit amounts in smallest currency unit
    - `totalCredit` number, double — Sum of all credit amounts in smallest currency unit
    - `currency` string — Property currency ISO code
    - `currencyScale` integer
  - `foreignCurrencyTotals` ForeignCurrencyTotals — Multi-currency totals across all matching transactions (all pages).
    - `debit` object — Map of currency code to total debit amount (e.g. {"RON": 724.82, "EUR": 5})
    - `credit` object — Map of currency code to total credit amount

## Other responses

- `400` — Bad Request

---

[API](https://skmtc.net/cloudbeds/apis/cloudbeds-api.md) · [All operations](https://skmtc.net/cloudbeds/apis/cloudbeds-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cloudbeds/cloudbeds-api/revisions/2faa857793e8/schema)