--- title: "Balance transactions" description: "2 operations, with parameters and examples." url: https://docs.fluveo.com/api/balance_transactions/ --- > Index of every page: https://docs.fluveo.com/llms.txt. Integrating Fluveo? Read https://docs.fluveo.com/agents/integrate.md first. > Too long? This page with code in one language only: https://docs.fluveo.com/api/balance_transactions.curl.md (cURL), https://docs.fluveo.com/api/balance_transactions.node.md (Node.js), https://docs.fluveo.com/api/balance_transactions.python.md (Python), https://docs.fluveo.com/api/balance_transactions.php.md (PHP). # Balance transactions 2 operations, with parameters and examples. A balance transaction is one line of the store's statement: a charge, refund, dispute adjustment, payout or fee that moved the balance. A reserve hold or release moves the reserve: its balance_type is risk_reserved, and every other line's is payments. Every line that moves the store's balance is listed; one the store's own payments, refunds and payouts did not make is an adjustment, with its own reporting_category. Send every request to `https://api.fluveo.com/v1` with your secret key as a Bearer token. This page lists only what Fluveo serves; [the OpenAPI file](https://docs.fluveo.com/openapi.json) holds the same operations. > **For AI agents:** > > Use plain HTTP; install no payments SDK. Send `Authorization: Bearer sk_test_...` and a fresh `Idempotency-Key` on every POST; reuse the same key only when you retry that same POST. Send only the documented parameters. ## Lists balance transaction objects, newest first `GET /v1/balance_transactions` Permission: [`rak_balance_read`](https://docs.fluveo.com/permissions.md#balance). **Query parameters** - `created` (object, optional): Filter on the creation time, a Unix timestamp: created= for an exact match, or created[gt], created[gte], created[lt], created[lte]. - `currency` (string, optional): Only balance transactions in this currency. - `ending_before` (string, optional): Cursor: the id of the first object of the current page, to get the previous page. Do not send it with starting_after. - `limit` (integer, optional): How many objects to return, from 1 to 100. Default 10. - `payout` (string, optional): Only the balance transactions paid out in this payout (po_...). - `source` (string, optional): Only the balance transactions of this object (ch_, re_, po_, ...). An id no line has gives an empty list. - `starting_after` (string, optional): Cursor: the id of the last object of the previous page, to get the next page. Do not send it with ending_before. - `type` (string, optional): Only this kind of balance transaction, such as charge, refund or payout. A type no line has gives an empty list. - `available_on` (object, optional): Filter on the time the funds become available, a Unix timestamp: available_on= for an exact match, or available_on[gt], available_on[gte], available_on[lt], available_on[lte]. **Headers** - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. Returns a list of [`balance_transaction`](https://docs.fluveo.com/api/balance_transactions.md#object-balance_transaction) objects. **Request** cURL: ```bash curl -G https://api.fluveo.com/v1/balance_transactions \ -H "Authorization: Bearer sk_test_..." \ --data-urlencode "limit=5" \ --data-urlencode "type=charge" ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/balance_transactions" + "?" + new URLSearchParams([["limit","5"],["type","charge"]]), { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/balance_transactions", headers={"Authorization": "Bearer sk_test_..."}, params=[("limit", "5"), ("type", "charge")], ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ``` ## Retrieves a balance transaction `GET /v1/balance_transactions/{id}` Permission: [`rak_balance_read`](https://docs.fluveo.com/permissions.md#balance). **Path parameters** - `id` (string, required): The object's id. **Headers** - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. Returns a [`balance_transaction`](https://docs.fluveo.com/api/balance_transactions.md#object-balance_transaction) object. **Request** cURL: ```bash curl https://api.fluveo.com/v1/balance_transactions/txn_123 \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/balance_transactions/txn_123", { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/balance_transactions/txn_123", headers={"Authorization": "Bearer sk_test_..."}, ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ``` ## The balance_transaction object Ids start with `txn_`. **Attributes** - `amount` (integer) - `available_on` (integer) - `balance_type` (enum): One of: `issuing`, `payments`, `refund_and_dispute_prefunding`, `risk_reserved`. - `created` (integer) - `currency` (string) - `description` (string, nullable) - `exchange_rate` (number, nullable) - `fee` (integer) - `fee_details` (array) - `id` (string) - `net` (integer) - `object` (enum): One of: `balance_transaction`. - `reporting_category` (string) - `source` (string, nullable) - `status` (string) - `type` (enum): One of: `adjustment`, `charge`, `connect_collection_transfer`, `payout`, `payout_cancel`, `payout_failure`, `refund`, `refund_failure`, `reserve_hold`, `reserve_release`, `reserved_funds`.