> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Introduction

## Article: Introduction

## Article Link: https://dev.wix.com/docs/api-reference/business-management/payments/wix-payments-provider/balances/introduction.md

## Article Content:

# About the Balance Records API

The Balance Records API is a read-only ledger of financial operations on a Wix Payments merchant account. Each balance record represents 1 financial operation (a payment, refund, chargeback, reserve hold or release, top-up, or Wix Capital movement) and how it affected the account's balance.

A balance record describes the effect of a financial operation on the balance, not the operation itself. For payment details such as the payment method, authorization, and capture, use the [Transactions API](https://dev.wix.com/docs/api-reference/business-management/payments/wix-payments-provider/transactions/introduction.md). Disputes are managed through the Disputes API, and each dispute's effect on the balance appears here as `CHARGEBACK` and `CHARGEBACK_FEE` records. To trigger or schedule a payout, use the Payouts API.

With the Balance Records API, you can:

- Query balance records by profile, payout, transaction, type, date range, or a named tag (for example, `AVAILABLE`, `PENDING`, or `RESERVE`).
- Retrieve a single balance record by ID.
- Get aggregate totals (gross, fees, and net) across any filter, in the same call.
- Preview the merchant's next reserve hold and release before they happen, via virtual estimated records.

For an in-depth conceptual map, including types, statuses, lifecycles, settlement, tags, virtual records, and immutability, see [About Balance Records](https://dev.wix.com/docs/api-reference/business-management/payments/wix-payments-provider/balances/about-balance-records.md).

## Records versus payouts

A balance record is 1 entry on the account ledger, caused by 1 financial operation. Payments, refunds, chargebacks, reserves, top-ups, and Wix Capital movements are owned by other services. The balance record is how their effect on the merchant's balance appears.

Payouts do not create balance records. A payout sends funds from the Wix Payments account to the merchant's bank, and stamps each settled record it includes with its `payoutId`.

## Before you begin

It's important to note the following points before starting to code:

- Records are immutable. The `amount`, `fee`, and `net` fields never change after creation. Adjustments are always expressed as new records. For example, a `REFUND_REVERSAL` is a new record, not an edit to the original `REFUND`.
- On every record, `net` equals `amount - fee`. A positive `amount` is a credit to the account, and a negative `amount` is a deduction.
- The `recordStatus` field is response-only and can't be used as a filter on list or query requests. To filter by a record's effect on the balance (for example, `AVAILABLE`, `PENDING`, or `RESERVE`), pass values to the `tags` request field instead.
- Records bundled into a payout move to `PAID_OUT`, with one exception: a `RESERVE_HOLD` in a payout ends at `DEDUCTED_FROM_PAYOUT`, because the held amount is subtracted from the payout total rather than sent to the merchant.
- `PAID_OUT` is used for both regular payouts and Wix Checking Instant Access transfers, distinguished by which detail block is populated. A record with `payoutInfo` was sent via a regular payout, where bank settlement can take several days. A record with `bookTransferInfo` was funded via a Wix Checking Instant Access transfer, where the funds are immediately available.
- One financial operation can produce more than one record. For example, a chargeback always produces a separate `CHARGEBACK_FEE` alongside the `CHARGEBACK`.

## Use cases

- [List the records inside a payout](invalid-url).
- [Find every balance record linked to a transaction](invalid-url).
- [Show what's pending versus available](invalid-url).
- [Project the merchant's next reserve activity](invalid-url).
- [Surface chargebacks and disputes for an account](invalid-url).

## Terminology

- **Balance record**: A single entry on the Wix Payments account ledger, describing how 1 financial operation affected the merchant's balance.
- **Account profile**: A sub-entity inside a Wix Payments account with its own balance and payouts. Every balance record belongs to exactly 1 profile.
- **Settlement**: The point when a credit record's funds become part of the available balance, after the pending period elapses. The record's `recordStatus` moves from `PENDING_CREDIT` to `CREDITED`.
- **Payout**: A transfer of the available balance to the merchant's bank account. A payout doesn't create balance records: it bundles settled records and stamps them with its `payoutId`.
- **Reserve**: Funds temporarily withheld from the available balance, expressed as a paired `RESERVE_HOLD` and `RESERVE_RELEASE`.
- **Tag**: A named filter shortcut (for example, `AVAILABLE` or `PENDING`) that the server expands into a composite filter at query time. Tags aren't stored on records.
- **Virtual record**: A projection of the merchant's next reserve hold or release, returned as the first result for the `ESTIMATED_RESERVE_HOLD` and `ESTIMATED_RESERVE_RELEASE` tags. It has no `id` and no `appliedDate`.

@sdk_package_setup