---
updatedAt: 2026-04-24T16:37:51.000Z
agentTools:
  projectIndex: https://developers.cloudbeds.com/llms.txt
---

# Search posted transactions

Search and retrieve posted transactions for a property. This endpoint uses POST (instead of GET) to support complex filter criteria in the request body. You can combine multiple filters with AND/OR logic, paginate results, and sort by various fields.

**Supported filter fields:**
  - `account_category`
  - `chart_of_account_type`
  - `created_at` (alias for `transaction_datetime`)
  - `customer_id`
  - `custom_code`
  - `external_relation_id`
  - `external_relation_kind`
  - `folio_id`
  - `id`
  - `internal_code`
  - `origin_id`
  - `parent_id`
  - `routed_from`
  - `source_id`
  - `source_identifier`
  - `source_kind`
  - `transaction_datetime`
  - `trial_balance_id`
  - `service_date`
  - `business_date`


**Supported sort fields:**
  - `created_at` (alias for `transaction_datetime`)
  - `id`
  - `internal_code`
  - `source_id`
  - `transaction_datetime`
  - `service_date`
  - `business_date`


**Required filter constraints:** The API has certain constraints for filters so that the system is able to efficiently query the data. Every request must include at least one of the following base filters:
  - `id` with operator `equals` or `in`
  - `source_id` together with `source_kind`
  - `source_identifier` together with `source_kind`
  - `external_relation_id` together with `external_relation_kind`
  - `transaction_datetime`
  - `service_date`
  - `business_date`
  - `trial_balance_id`


**Additional filter rules:**
  - Filters cannot be empty.
  - `source_id` requires `source_kind` to be present in the same request.
  - `source_identifier` requires `source_kind` to be present in the same request.
  - `external_relation_id` and `external_relation_kind` must always be used together.
  - `trial_balance_id` only supports the `equals` operator and cannot appear more than once.
  - When using a single filter condition (without `and`/`or`), only `id`, `transaction_datetime`,
    `service_date` are allowed, and the operator must be `equals` or `in`.


**Example — single filter condition (no AND/OR needed):**
```
  {
    "filters": {
      "field": "id",
      "operator": "in",
      "value": [101, 102, 103]
    }
  }
```

```
  {
    "filters": {
      "field": "service_date",
      "operator": "equals",
      "value": "2024-01-01"
    }
  }
```

**Example — composite filter condition:**
```
  {
    "filters": {
      "and": [
        {
          "field": "transaction_datetime",
          "operator": "greater_than_or_equal",
          "value": "2024-01-01T00:00:00Z"
        },
        {
          "field": "transaction_datetime",
          "operator": "less_than",
          "value": "2024-02-01T00:00:00Z"
        }
      ]
    }
  }
```

**Example — composite filter condition with sorting and pagination:**
```
  {
    "filters": {
      "and": [
        {
          "operator": "greater_than_or_equal",
          "value": "2019-01-11T08:59:00Z",
          "field": "transaction_datetime"
        },
        {
          "operator": "equals",
          "value": "123",
          "field": "source_id"
        },
        {
          "operator": "equals",
          "value": "RESERVATION",
          "field": "source_kind"
        },
        {
          "or": [
            {
              "operator": "in",
              "value": ["1", "2", "3"],
              "field": "customer_id"
            },
            {
              "operator": "equals",
              "value": "9000",
              "field": "internal_code"
            }
          ]
        }
      ]
    },
    "pageToken": null,
    "limit": 10,
    "sort": [
      {
        "field": "transaction_datetime",
        "direction": "asc"
      }
    ]
  }
```


# OpenAPI definition

````json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Accounting API",
    "version": "v0",
    "description": "The Accounting API provides programmatic access to financial data and operations for hospitality properties. Use this API to manage transactions, folios, deposits, accounts receivable ledgers, trial balances, and related accounting configuration.\n\n**Key concepts:**\n- **Transactions** represent individual financial entries (charges, payments,\n  taxes, fees) associated with a source such as a reservation, group profile,\n  or house account.\n\n- **Folios** organize transactions into logical groups within a source. You\n  can create custom folios and move or route transactions between them.\n\n- **Source Balances** provide a real-time financial summary (charges, payments,\n  balance due, tax/fee breakdowns) for a reservation, group profile, house\n  account, or accounts receivable ledger.\n\n- **Accounts Receivable (AR) Ledgers** track outstanding balances that have\n  been transferred from reservations or group profiles for later collection.\n\n- **Trial Balance** is a daily financial reconciliation report that summarizes\n  ledger activity across guest, deposit, and AR ledgers.\n\n- **Custom Codes** let you map Cloudbeds internal transaction codes to your\n  own chart-of-accounts codes and general ledger codes.\n\n\n**Authentication:**\nAll endpoints require a valid OAuth2 bearer token. Endpoints are protected by scopes: `read:payment` for read operations and `write:payment` for mutating operations. A few search endpoints use POST with a request body to support complex filter criteria; these require the `read:payment` scope.\n\n**Base URL:**\nUse `https://api.cloudbeds.com` for production and `https://api.cloudbeds-stage.com` for staging. All endpoint paths are prefixed with `/accounting/v1.0`.\n\n**Property context:**\nEvery request must include the `X-Property-ID` header to identify which property the request applies to.\n\n**Monetary amounts:**\nUnless otherwise noted, monetary amounts are expressed in the smallest currency unit (e.g., cents for USD). Use the `currencyScale` field to determine the number of decimal places.\n\n**Pagination:**\nPaginated endpoints return a `nextPageToken` value. Pass this token in subsequent requests to retrieve the next page of results. When `nextPageToken` is null or absent, you have reached the last page.\n"
  },
  "servers": [
    {
      "url": "https://api.cloudbeds.com"
    }
  ],
  "paths": {
    "/accounting/v1.0/transactions": {
      "post": {
        "summary": "Search posted transactions",
        "description": "Search and retrieve posted transactions for a property. This endpoint uses POST (instead of GET) to support complex filter criteria in the request body. You can combine multiple filters with AND/OR logic, paginate results, and sort by various fields.\n\n**Supported filter fields:**\n  - `account_category`\n  - `chart_of_account_type`\n  - `created_at` (alias for `transaction_datetime`)\n  - `customer_id`\n  - `custom_code`\n  - `external_relation_id`\n  - `external_relation_kind`\n  - `folio_id`\n  - `id`\n  - `internal_code`\n  - `origin_id`\n  - `parent_id`\n  - `routed_from`\n  - `source_id`\n  - `source_identifier`\n  - `source_kind`\n  - `transaction_datetime`\n  - `trial_balance_id`\n  - `service_date`\n  - `business_date`\n\n\n**Supported sort fields:**\n  - `created_at` (alias for `transaction_datetime`)\n  - `id`\n  - `internal_code`\n  - `source_id`\n  - `transaction_datetime`\n  - `service_date`\n  - `business_date`\n\n\n**Required filter constraints:** The API has certain constraints for filters so that the system is able to efficiently query the data. Every request must include at least one of the following base filters:\n  - `id` with operator `equals` or `in`\n  - `source_id` together with `source_kind`\n  - `source_identifier` together with `source_kind`\n  - `external_relation_id` together with `external_relation_kind`\n  - `transaction_datetime`\n  - `service_date`\n  - `business_date`\n  - `trial_balance_id`\n\n\n**Additional filter rules:**\n  - Filters cannot be empty.\n  - `source_id` requires `source_kind` to be present in the same request.\n  - `source_identifier` requires `source_kind` to be present in the same request.\n  - `external_relation_id` and `external_relation_kind` must always be used together.\n  - `trial_balance_id` only supports the `equals` operator and cannot appear more than once.\n  - When using a single filter condition (without `and`/`or`), only `id`, `transaction_datetime`,\n    `service_date` are allowed, and the operator must be `equals` or `in`.\n\n\n**Example — single filter condition (no AND/OR needed):**\n```\n  {\n    \"filters\": {\n      \"field\": \"id\",\n      \"operator\": \"in\",\n      \"value\": [101, 102, 103]\n    }\n  }\n```\n\n```\n  {\n    \"filters\": {\n      \"field\": \"service_date\",\n      \"operator\": \"equals\",\n      \"value\": \"2024-01-01\"\n    }\n  }\n```\n\n**Example — composite filter condition:**\n```\n  {\n    \"filters\": {\n      \"and\": [\n        {\n          \"field\": \"transaction_datetime\",\n          \"operator\": \"greater_than_or_equal\",\n          \"value\": \"2024-01-01T00:00:00Z\"\n        },\n        {\n          \"field\": \"transaction_datetime\",\n          \"operator\": \"less_than\",\n          \"value\": \"2024-02-01T00:00:00Z\"\n        }\n      ]\n    }\n  }\n```\n\n**Example — composite filter condition with sorting and pagination:**\n```\n  {\n    \"filters\": {\n      \"and\": [\n        {\n          \"operator\": \"greater_than_or_equal\",\n          \"value\": \"2019-01-11T08:59:00Z\",\n          \"field\": \"transaction_datetime\"\n        },\n        {\n          \"operator\": \"equals\",\n          \"value\": \"123\",\n          \"field\": \"source_id\"\n        },\n        {\n          \"operator\": \"equals\",\n          \"value\": \"RESERVATION\",\n          \"field\": \"source_kind\"\n        },\n        {\n          \"or\": [\n            {\n              \"operator\": \"in\",\n              \"value\": [\"1\", \"2\", \"3\"],\n              \"field\": \"customer_id\"\n            },\n            {\n              \"operator\": \"equals\",\n              \"value\": \"9000\",\n              \"field\": \"internal_code\"\n            }\n          ]\n        }\n      ]\n    },\n    \"pageToken\": null,\n    \"limit\": 10,\n    \"sort\": [\n      {\n        \"field\": \"transaction_datetime\",\n        \"direction\": \"asc\"\n      }\n    ]\n  }\n```\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/propertyIdHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ListTransactionsRequest"
              }
            }
          },
          "required": true
        },
        "operationId": "listTransactions",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "oauth2": [
              "read:payment"
            ]
          }
        ],
        "tags": [
          "Transactions"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListTransactionsPaginated"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      },
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "implicit": {
            "authorizationUrl": "https://hotels.cloudbeds.com/api/v1.2/oauth",
            "scopes": {
              "read:payment": "Read payment and transaction information",
              "write:payment": "Create, update, or delete payment and transaction data"
            }
          }
        }
      }
    },
    "parameters": {
      "propertyIdHeader": {
        "name": "X-Property-ID",
        "in": "header",
        "required": true,
        "schema": {
          "type": "integer",
          "format": "int64"
        },
        "description": "Unique identifier of the property. Required for all requests to scope data to a specific property.\n"
      }
    },
    "responses": {
      "400": {
        "description": "Bad Request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiAccountingError"
            }
          }
        }
      }
    },
    "schemas": {
      "AnyValue": {
        "description": "Can be any of supported OpenApi types."
      },
      "ApiAccountingError": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "errorCode": {
            "$ref": "#/components/schemas/ApiErrorCode"
          },
          "errorDetails": {
            "type": "string"
          }
        }
      },
      "ApiErrorCode": {
        "type": "string",
        "description": "Error code indicating the type of failure. Use this value for programmatic error handling.\n- `UNKNOWN_ERROR` — An unclassified error occurred. Contact support if this persists.\n- `UNEXPECTED_ERROR` — An unexpected internal error occurred. Retry the request or contact support.\n- `ACCESS_DENIED` — You do not have permission to perform this operation on the specified property.\n- `INVALID_REQUEST` — The request body or parameters are invalid. Check the errorDetails field for specifics.\n- `NOT_UNIQUE_VALUE` — A value that must be unique (such as a name or code) already exists.\n- `INVALID_USER_INFORMATION` — The user information provided is invalid or could not be resolved.\n- `ENTITY_NOT_FOUND` — The requested entity was not found.\n- `ACCOUNTS_RECEIVABLE_LEDGER_FEATURE_DISABLED` — The accounts receivable ledger feature is not enabled for this property.\n- `BOOKING_NOT_FOUND` — The specified reservation or booking was not found.\n- `ACCOUNTS_RECEIVABLE_LEDGER_NOT_FOUND` — The specified accounts receivable ledger was not found.\n- `ACCOUNTS_RECEIVABLE_LEDGER_STATUS_ERROR` — The AR ledger is in a status that does not allow this operation (e.g., attempting to transfer to a closed ledger).\n- `BOOKING_STATUS_ERROR` — The reservation is in a status that does not allow this operation.\n- `GROUP_PROFILE_NOT_FOUND` — The specified group profile was not found.\n- `GROUP_PROFILE_STATUS_ERROR` — The group profile is in a status that does not allow this operation.\n- `GROUP_PROFILE_FOLIO_ERROR` — An error occurred with the group profile folio (e.g., the specified folio does not belong to the group profile).\n- `DEPOSIT_TRANSACTION_CAN_NOT_BE_TRANSFERRED` — The deposit transaction cannot be transferred.\n- `INVALID_ARGUMENT_ERROR` — A provided argument is invalid (e.g., an unrecognized filter or sort field). Check the errorDetails field for specifics.\n- `FOLIO_HAS_TRANSACTIONS` — The folio cannot be deleted because it has transactions assigned to it. Move or unroute the transactions first.\n- `SOURCE_HAS_ROUTED_TRANSACTIONS` — The source's folio configuration cannot be changed because it has routed transactions involving its folios (transactions originating from a reservation source, or routed onto a group source). Unroute the transactions first.\n",
        "enum": [
          "UNKNOWN_ERROR",
          "UNEXPECTED_ERROR",
          "ACCESS_DENIED",
          "INVALID_REQUEST",
          "NOT_UNIQUE_VALUE",
          "INVALID_USER_INFORMATION",
          "ENTITY_NOT_FOUND",
          "ACCOUNTS_RECEIVABLE_LEDGER_FEATURE_DISABLED",
          "BOOKING_NOT_FOUND",
          "ACCOUNTS_RECEIVABLE_LEDGER_NOT_FOUND",
          "ACCOUNTS_RECEIVABLE_LEDGER_STATUS_ERROR",
          "BOOKING_STATUS_ERROR",
          "GROUP_PROFILE_NOT_FOUND",
          "GROUP_PROFILE_STATUS_ERROR",
          "GROUP_PROFILE_FOLIO_ERROR",
          "DEPOSIT_TRANSACTION_CAN_NOT_BE_TRANSFERRED",
          "INVALID_ARGUMENT_ERROR",
          "FOLIO_HAS_TRANSACTIONS",
          "SOURCE_HAS_ROUTED_TRANSACTIONS"
        ]
      },
      "sortDirection": {
        "type": "string",
        "enum": [
          "asc",
          "desc"
        ],
        "x-enum-varnames": [
          "asc",
          "desc"
        ],
        "description": "Direction for sort - asc or desc"
      },
      "ListTransactionsRequest": {
        "type": "object",
        "required": [
          "filters"
        ],
        "properties": {
          "filters": {
            "$ref": "#/components/schemas/Filters"
          },
          "pageToken": {
            "type": "string"
          },
          "limit": {
            "description": "Optional parameter. Default value is 100, maximum value is 1100.",
            "default": 100,
            "type": "integer",
            "format": "int32"
          },
          "sort": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Sort"
            }
          }
        }
      },
      "ListTransactionsPaginated": {
        "type": "object",
        "properties": {
          "transactions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TransactionResponse"
            }
          },
          "nextPageToken": {
            "$ref": "#/components/schemas/NextPageToken"
          }
        }
      },
      "TransactionResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Id of the transaction."
          },
          "propertyId": {
            "type": "string",
            "description": "Property ID where the transaction was created."
          },
          "internalTransactionCode": {
            "type": "string",
            "description": "Internal code for the transaction, managed by Cloudbeds."
          },
          "customTransactionCode": {
            "type": "string",
            "description": "Custom code for the transaction, managed by Property."
          },
          "generalLedgerCustomCode": {
            "type": "string",
            "description": "Custom code for general ledger, managed by Property."
          },
          "amount": {
            "type": "number",
            "description": "Amount of the transaction."
          },
          "currencyScale": {
            "type": "integer",
            "description": "Number of decimal places for the currency."
          },
          "currency": {
            "type": "string",
            "description": "Currency (ISO code) applied to the amount of the transaction."
          },
          "customerId": {
            "type": "string",
            "description": "Id of the user who perform the transaction, also know as guest id."
          },
          "rootId": {
            "type": "string",
            "description": "Root Id of the transaction, it contains the id of the transaction that is related to it."
          },
          "parentId": {
            "type": "string",
            "description": "Id of the transaction that is parent of this one. For example Tax on top of a rate, tax on top of a fee, etc."
          },
          "sourceId": {
            "type": "string",
            "description": "Id of the source. It is related with the source_kind, so if sourceKind is RESERVATION, is the reservation id."
          },
          "subSourceId": {
            "type": "string",
            "description": "Id of the sub source. At the moment only for reservations that is the booking_room_id."
          },
          "sourceKind": {
            "$ref": "#/components/schemas/SourceKind"
          },
          "account": {
            "$ref": "#/components/schemas/Account"
          },
          "externalRelationId": {
            "type": "string",
            "description": "External relation id, for example if the transaction is a payment it will contain payment id."
          },
          "externalRelationKind": {
            "type": "string",
            "enum": [
              "ROOM",
              "PAYMENT",
              "ITEM",
              "ITEM_POS",
              "ADDON",
              "RESERVATION",
              "ACCOUNTS_RECEIVABLE",
              "ROOM_REVENUE",
              "TAX",
              "FEE",
              "ADJUSTMENT",
              "PAYMENT_FEE",
              "BOOKABLE_RESOURCE",
              "CHANNEL_COMMISSION",
              "GRATUITY",
              "CHECK_ITEM",
              "CHECK_SERVICE_CHARGE",
              "CHECK_DISCOUNT",
              "CHANNEL_COMMISSION_MANUAL"
            ],
            "description": "Kind of the external relation id, for example if transaction is a payment it will contain PAYMENT."
          },
          "originId": {
            "type": "string",
            "description": "Id of origin of the transaction. For example if the transaction is created based on a rate, is the rate id."
          },
          "routedFrom": {
            "type": "string",
            "description": "Id of the transaction that was routed from. It can be null."
          },
          "quantity": {
            "type": "integer",
            "format": "int32",
            "description": "Amount of items purchased."
          },
          "description": {
            "type": "string",
            "description": "Description of the transaction."
          },
          "userId": {
            "type": "string",
            "description": "ID of the user who created the transaction"
          },
          "sourceDatetime": {
            "type": "string",
            "example": "2017-07-21T17:32:28Z",
            "description": "Date time the source was created. (ISO 8601) in UTC",
            "format": "date-time"
          },
          "transactionDatetime": {
            "type": "string",
            "example": "2017-07-21T17:32:28Z",
            "description": "Date time when the transaction should be created at. (ISO 8601) in UTC",
            "format": "date-time"
          },
          "transactionDatetimePropertyTime": {
            "type": "string",
            "description": "Date time when the transaction should be created at base on the property timezone.",
            "format": "date-time"
          },
          "serviceDate": {
            "type": "string",
            "example": "2017-07-21",
            "description": "Date when the posted transaction was created (property time).",
            "format": "date"
          },
          "businessDate": {
            "type": "string",
            "example": "2026-06-21",
            "description": "Business date the posted transaction belongs to (property time), aligned to night audit.",
            "format": "date"
          },
          "createdAt": {
            "type": "string",
            "example": "2017-07-21T17:32:28Z",
            "description": "Date time when the transaction was inserted on the database. (ISO 8601) in UTC",
            "format": "date-time"
          },
          "sourceIdentifier": {
            "type": "string",
            "example": "38883261663",
            "description": "If source_kind = RESERVATION, this field will contain a reservation identifier. For a transaction with source_kind = GROUP_PROFILE, this field will contain a group code. For source_king = HOUSE_ACCOUNT it will be null."
          },
          "subSourceIdentifier": {
            "type": "string",
            "example": "38883261663-2",
            "description": "identifier of a booking room"
          },
          "notes": {
            "type": "string",
            "description": "Notes associated with the transaction"
          }
        }
      },
      "Account": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID of account"
          },
          "description": {
            "type": "string",
            "description": "Description of the account"
          },
          "name": {
            "type": "string",
            "description": "Name of the account"
          },
          "category": {
            "$ref": "#/components/schemas/AccountCategory"
          },
          "chartOfAccountType": {
            "$ref": "#/components/schemas/ChartOfAccountType"
          }
        }
      },
      "SourceKind": {
        "type": "string",
        "enum": [
          "RESERVATION",
          "HOUSE_ACCOUNT",
          "GROUP_PROFILE",
          "ACCOUNTS_RECEIVABLE_LEDGER"
        ],
        "description": "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.\n"
      },
      "AccountCategory": {
        "type": "string",
        "enum": [
          "DEPOSITS"
        ],
        "description": "Account category"
      },
      "ChartOfAccountType": {
        "type": "string",
        "enum": [
          "LIABILITIES",
          "REVENUE",
          "ASSETS",
          "EQUITY",
          "EXPENSES"
        ],
        "description": "Chart of account type"
      },
      "ConditionalOperator": {
        "type": "string",
        "enum": [
          "greater_than_or_equal",
          "greater_than",
          "less_than_or_equal",
          "less_than",
          "equals",
          "not_equals",
          "in",
          "not_in",
          "contains",
          "not_contains",
          "is_null",
          "not_null"
        ],
        "x-enum-varnames": [
          "greater_than_or_equal",
          "greater_than",
          "less_than_or_equal",
          "less_than",
          "equals",
          "not_equals",
          "in",
          "not_in",
          "contains",
          "not_contains",
          "is_null",
          "not_null"
        ]
      },
      "FieldFilter": {
        "type": "object",
        "required": [
          "operator",
          "field"
        ],
        "properties": {
          "operator": {
            "$ref": "#/components/schemas/ConditionalOperator"
          },
          "value": {
            "$ref": "#/components/schemas/AnyValue"
          },
          "field": {
            "type": "string"
          }
        }
      },
      "Filters": {
        "type": "object",
        "oneOf": [
          {
            "$ref": "#/components/schemas/AndOrGroup"
          },
          {
            "$ref": "#/components/schemas/FieldFilter"
          }
        ]
      },
      "AndOrGroup": {
        "type": "object",
        "properties": {
          "and": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/AndOrGroup"
                },
                {
                  "$ref": "#/components/schemas/FieldFilter"
                }
              ]
            }
          },
          "or": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/AndOrGroup"
                },
                {
                  "$ref": "#/components/schemas/FieldFilter"
                }
              ]
            }
          }
        }
      },
      "Sort": {
        "type": "object",
        "required": [
          "field",
          "direction"
        ],
        "properties": {
          "field": {
            "type": "string"
          },
          "direction": {
            "$ref": "#/components/schemas/sortDirection"
          }
        }
      },
      "NextPageToken": {
        "type": "string",
        "description": "Token for fetching the next page of results"
      }
    }
  }
}
````