CLcloudbeds
Folios

Search folio 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.

post/accounting/v1.0/folios/transactions

Request

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

Headers

X-Property-IDinteger required

Unique identifier of the property. Required for all requests to scope data to a specific property.

Request body

sourceIdinteger 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.

folioIdinteger

Filter by specific folio

postedboolean

Filter by posted status. Omit to include both posted and pending.

descriptionFiltersstring[]

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.

transactionDateFromstring date-time

Filter transactions from this datetime (UTC, inclusive)

transactionDateTostring date-time

Filter transactions to this datetime (UTC, inclusive)

serviceDateFromstring date

Filter by service date from (inclusive)

serviceDateTostring date

Filter by service date to (inclusive)

subSourceIdsinteger[]

Filter by sub-source IDs (booking room IDs for reservations)

searchQuerystring

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".

pageTokenstring
limitinteger

Page size. Default 100, max 1100.

includeVoidedboolean

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.

includeTotalboolean

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.

Example request

{
  "sourceId": 38883261663,
  "descriptionFilters": [
    "product_109574517547138",
    "ebanking",
    "rate"
  ]
}

Response

OK

groupsobject

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.

nextPageTokenstring

Token for fetching the next page of results

Changes

No recorded changes to this operation across all 1 revision of this API.