--- title: "List transactions" method: GET path: "/v1/transactions" tags: ["Transaction"] --- # List transactions `GET /v1/transactions` Returns a paginated list of accounting-ledger transactions for the company. Each row is a unified projection of a card transaction, bank transfer, payment, commission, invoice or balance correction, and carries its rendición (expense-tracking) custom-column values. ## Key features - **Pagination**: `_start` / `_end` (default 25 items). `Content-Range` and `X-Total-Count` headers describe the window. - **Sorting**: `_field` / `_order`. Sortable virtual fields include `cartola_date` (the default), `merchant_name`, `card_name`, `card_last4`, `amount`, `target_amount`, `cumulative_balance` and `created_at`. - **Filtering**: any column can be filtered with a plain value or a JSON operator string (e.g. `{"$gte": ...}`, `{"$in": [...]}`, `{"$like": "%...%"}`). - **Cumulative balances**: pass `_with_cumulative_balances=true` to inject running balances (`target_cumulative_balance_with_commission`). This requires a resolvable company. - **Hide commissions**: pass `_hide_commissions=true` to omit commission rows. ## Amount encoding Most monetary fields are serialized as strings of integer cents. `exchange_rate` is a human-formatted string; use `exchange_rate_value` for a machine-parseable rate. ## Authorization Non-admin callers see only transactions of companies where they hold the `transactions_view` permission, plus their own transactions. Scoping is per-user across the caller's permitted companies (via policy scope); the `company-id` header is **not** used to scope this list and an absent/mismatched header does not by itself produce a `401`. ## Query parameters - `_start` integer - `_end` integer - `_order` 'asc' | 'desc' - `_field` string - `_with_cumulative_balances` 'true' | 'false' - `_hide_commissions` 'true' | 'false' - `transaction_type` string - `status` string - `cartola_id` string, uuid - `cartola_date` string ## Headers - `company-id` string, uuid, required ## Response `200` Paginated list of transactions - Transaction[] - `id` string, uuid, required — The transaction id. This is the `accounting_ledger_tx_id` and is the identifier used by the file, label and reconciliation endpoints. - `accounting_ledger_tx_id` string, uuid — The underlying `Accounting::LedgerTx` id. Equal to `id`; exposed as a distinct field for clients that key off the ledger id explicitly. - `company_id` string, uuid — The company that owns the transaction. - `user_id` string, nullable — The user associated with the transaction, if any. - `account_id` string, uuid, nullable — The account the transaction belongs to. - `account` object, nullable — The account record associated with the transaction. - `card_id` string, nullable — The card id, for card transactions. - `card_name` string, nullable — The card name, present only for `card_transactions`. - `card_last4` string, nullable — Last four digits of the card, present only for `card_transactions`. - `description` string, nullable — Human description of the transaction. - `comments` string, nullable — Internal comments/notes on the transaction. - `transaction_type` 'card_transactions' | 'banking_bank_transactions' | 'payments' | 'commissions' | 'commission_refunds' | 'invoices', required — The kind of underlying record projected into the ledger. - `status` string, required — Current status of the transaction (values depend on the source type). - `status_reason` string, nullable — Reason for the current status, present only for `card_transactions`. - `amount` string, nullable — Source amount in integer cents, serialized as a string. - `currency` string, nullable — Source currency (ISO 4217). - `charge` string — Negative (or zero) side of the amount in integer cents (outflow), serialized as a string (`"0"` when there is no charge side). - `deposit` string — Positive (or zero) side of the amount in integer cents (inflow), serialized as a string (`"0"` when there is no deposit side). - `amount_in_clp` string, nullable — Amount converted to CLP in integer cents, serialized as a string. - `exchange_rate` string — Human-formatted FX rate applied to the row (thousands separator `,`, decimal `.`). Empty string when the rate is genuinely unknown. Use `exchange_rate_value` for a machine-parseable rate. - `exchange_rate_value` string, nullable — Machine-parseable FX rate (no thousands separator), serialized as a string to preserve precision, or `null` for cross-currency rows whose rate is genuinely unknown. - `target_amount` string, nullable — Amount in the target currency in integer cents, serialized as a string. - `target_currency` string, nullable — Target currency (ISO 4217, lower-cased in the ledger view). - `target_cumulative_balance_with_commission` integer, nullable — Running balance in cents including commissions. Only computed when the list is requested with cumulative balances (`_with_cumulative_balances=true`) or on the CSV export. - `source_type` string, nullable — Polymorphic type of the underlying source record. - `source_id` string, nullable — Polymorphic id of the underlying source record. - `commission_amount` string — Commission amount in integer cents, serialized as a string. An empty string (`""`) is returned when the row has no associated commission ledger entry. - `commission_currency` string, nullable — Commission currency. - `commission_percentage` string, nullable — Commission percentage applied. - `merchant_name` string, nullable — Merchant/recipient name (card merchant or bank recipient). - `merchant_image_url` string, nullable — Merchant logo URL (card transactions only). - `affects_balance` boolean — Whether this transaction affects the account balance. - `cartola_id` string, uuid, nullable — The cartola (statement) this transaction is assigned to, if any. - `cartola_date` string, date-time, nullable — The accounting date used to place the transaction in a cartola. - `authorized_at` string, date-time, nullable — Timestamp when the transaction was authorized. - `cumulative_balance` integer, nullable — Running balance in cents. A virtual attribute aliased to the persisted ledger value (`target_cumulative_balance_cents`), so the key is **always present** — it holds the value stored on the ledger row. `cumulative_balance` and `target_cumulative_balance` are aliases of the SAME underlying value. Only the on-the-fly window-function **recomputation** of these balances is gated on `_with_cumulative_balances=true` (and on the CSV export); without it the persisted value is returned. - `target_cumulative_balance` integer, nullable — Running balance in cents. Aliased to the SAME persisted ledger value as `cumulative_balance` (`target_cumulative_balance_cents`); both keys are **always present** and carry the same number. Only the window-function **recomputation** is gated on `_with_cumulative_balances=true` (or the CSV export). - `created_at` string, date-time — When the underlying transaction record was created. - `updated_at` string, date-time — When the underlying transaction record was last updated. - `custom_column_values` object[] — Rendición (expense-tracking) custom-column values attached to the transaction. Each entry pairs a custom column with its stored value and displayable value. - `custom_column_id` string, uuid - `value` string, nullable - `displayable_value` string, nullable ## Other responses - `401` — Unauthorized — missing/invalid `Authorization`. The body is empty for the shared auth guard; branch on the status code, not the body. --- [API](https://skmtc.net/cardda/apis/banking-api.md) · [All operations](https://skmtc.net/cardda/apis/banking-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cardda/banking-api/versions/ff1aeb3fda8b/schema)