> 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 # QueryBalanceRecords # Package: wixPaymentsProvider # Namespace: BalanceRecordsService # Method link: https://dev.wix.com/docs/api-reference/business-management/payments/wix-payments-provider/balances/query-balance-records.md ## Permission Scopes: View settlement reports and payouts: SCOPE.PAYMENTS.PAYOUTS-VIEW-FOR-SITE ## Introduction Retrieves a list of up to 1000 balance records, given the provided paging, filtering, and sorting. Query Balance Records runs with these defaults, which you can override: - `query.sort[0].fieldName` is `applied_date` in `ASC` order - `query.paging.limit` is `20` - `query.paging.offset` is `0` (and `offset` is required when `paging` is set) Filter and sort field names inside `query` must be **snake_case**. They're read from the `query.filter` object and aren't auto-converted. Supported filter fields: `account_profile_id`, `tags`, `payout_id`, `transaction_id`, `types`, and the date ranges `transaction_creation_date`, `paid`, and `created_date`. Any other field returns an `Unsupported query: unknown parameter ` error. ID fields accept a single value by equality, `tags` and `types` accept `$in`, and date-range fields accept `$gte` and `$lt`. Supported `sort[i].fieldName` values: `applied_date`, `payment_info.created_date`, `created_date`. At most 1 sort field is allowed. To list every balance record in a payout, filter by `payout_id`. To learn about working with Query methods, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md), [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md), and [Field Projection](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-field-projection.md). --- ## REST API ### Schema ``` Method: queryBalanceRecords Description: Retrieves a list of up to 1000 balance records, given the provided paging, filtering, and sorting. Query Balance Records runs with these defaults, which you can override: - `query.sort[0].fieldName` is `applied_date` in `ASC` order - `query.paging.limit` is `20` - `query.paging.offset` is `0` (and `offset` is required when `paging` is set) Filter and sort field names inside `query` must be **snake_case**. They're read from the `query.filter` object and aren't auto-converted. Supported filter fields: `account_profile_id`, `tags`, `payout_id`, `transaction_id`, `types`, and the date ranges `transaction_creation_date`, `paid`, and `created_date`. Any other field returns an `Unsupported query: unknown parameter ` error. GUID fields accept a single value by equality, `tags` and `types` accept `$in`, and date-range fields accept `$gte` and `$lt`. Supported `sort[i].fieldName` values: `applied_date`, `payment_info.created_date`, `created_date`. At most 1 sort field is allowed. To list every balance record in a payout, filter by `payout_id`. To learn about working with Query methods, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md), [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md), and [Field Projection](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-field-projection.md). URL: https://www.wixapis.com/wixpay-balances/v5/balance-records/query Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: accountId Method parameters: param name: accountId | type: accountId | description: GUID of the Wix Payments account that owns the balance records. Retrieve account GUIDs from the Accounts API. | required: true | validation: format GUID param name: excludeTotal | type: excludeTotal | description: Whether to omit the total record count from `metadata.total`. Omitting the total can improve performance on large result sets. Default: `false` param name: includeSummary | type: includeSummary | description: Whether to include the aggregated `summary` in the response. When `true`, totals are computed across the records that matched the query (not across the whole account) and returned in `summary`. Default: `false` param name: query | type: Query - name: filter | type: Value | description: Filter object in the following format: `"filter" : { "fieldName1": "value1", "fieldName2":{"$operator":"value2"} }` Example of operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, `$contains` - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: values | type: array | description: - name: sort | type: array | description: Sort object in the following format: `[{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]` - name: fieldName | type: string | description: Name of the field to sort by. | validation: maxLength 512 - name: order | type: SortOrder | description: Sort order. - enum: ASC, DESC - name: origin | type: AddressLocation | description: Origin point for geo-distance sorting on a GEO field results are ordered by distance from this point (ASC = nearest first, DESC = farthest first). - name: latitude | type: number | description: Address latitude. | validation: format double - name: longitude | type: number | description: Address longitude. | validation: format double - name: paging | type: Paging | description: Paging options to limit and skip the number of items. - name: limit | type: integer | description: Number of items to load. | validation: minimum 0, format int32 - name: offset | type: integer | description: Number of items to skip in the current sort order. | validation: minimum 0, format int32 - name: fields | type: array | description: Array of projected fields. A list of specific field names to return. If `fieldsets` are also specified, the union of `fieldsets` and `fields` is returned. - name: fieldsets | type: array | description: Array of named, predefined sets of projected fields. A array of predefined named sets of fields to be returned. Specifying multiple `fieldsets` will return the union of fields from all sets. If `fields` are also specified, the union of `fieldsets` and `fields` is returned. Return type: QueryBalanceRecordsResponse - name: records | type: array | description: Retrieved balance records. | validation: maxItems 1000 - name: id | type: string | description: Balance record GUID. Not returned for virtual records produced by `ESTIMATED_RESERVE_HOLD` or `ESTIMATED_RESERVE_RELEASE` tags. | validation: format GUID - name: accountId | type: string | description: GUID of the Wix Payments account this balance record belongs to. | validation: format GUID - name: accountProfileId | type: string | description: GUID of the Wix Payments account profile this balance record belongs to. | validation: format GUID - name: amount | type: Money | description: Gross amount of the balance record, including fees. Positive for credits to the account, negative for deductions. - name: value | type: string | description: Monetary amount. Decimal string with a period as a decimal separator (e.g., 3.99). Optionally, a single (-), to indicate that the amount is negative. | validation: format DECIMAL_VALUE - name: currency | type: string | description: Currency code. Must be valid ISO 4217 currency code (e.g., USD). | validation: format CURRENCY - name: formattedValue | type: string | description: Monetary amount. Decimal string in local format (e.g., 1 000,30). Optionally, a single (-), to indicate that the amount is negative. - name: fee | type: Money | description: Fee that Wix Payments collected on this balance record. - name: net | type: Money | description: Net amount of the balance record after subtracting `fee`. - name: recordType | type: BalanceRecordType | description: Type of the balance record. Describes what kind of money movement this record represents. - enum: - UNKNOWN: Unknown balance record type. - CREDIT: Payment from a buyer for a sale, credited to the merchant's Wix Payments account. - REFUND: Refund issued back to a buyer. - CHARGEBACK: Chargeback initiated by a buyer against a previous payment. - REFUND_REVERSAL: Reversal of a previously issued refund. - CHARGEBACK_REVERSAL: Reversal of a previously issued chargeback. - RESERVE_HOLD: Funds withheld from the available balance as part of a reserve. - RESERVE_RELEASE: Funds returned to the available balance from a previously held reserve. - TOPUP: Transfer of funds from the merchant's external account into their Wix Payments account. - CREDIT_FAILED: Failure on a previously credited payment, resulting in a deduction from the balance. - CHARGEBACK_FEE: Fee charged for processing a chargeback. - CHARGEBACK_FEE_REVERSAL: Reversal of a previously charged chargeback fee. - CAPITAL_CASH_ADVANCE: Cash advance disbursed to the merchant from Wix Capital. - CAPITAL_AUTOMATIC_REMITTANCE: Automatic remittance taken from sales to repay a Wix Capital cash advance. - CAPITAL_ADJUSTMENT: Adjustment applied to a Wix Capital cash advance balance. - name: recordStatus | type: BalanceRecordStatus | description: Current effect of this record on the account balance. The value depends on the record's `recordType`, whether it has a `payoutInfo` or `bookTransferInfo`, and its `payoutAvailabilityDate`. This field is returned on responses only and can't be passed as a filter on list or query requests. To filter by effect on the balance, use `tags` instead. - enum: - UNKNOWN: Unknown balance record status. - PENDING_CREDIT: Funds from this record are added to the available balance once they settle. They aren't yet part of the available balance. - CREDITED: Funds from this record are part of the available balance. - RESERVED: Funds from this record are held in reserve and aren't part of the available balance. Applied to `RESERVE_HOLD` records, and to `RESERVE_RELEASE` records whose `payoutAvailabilityDate` hasn't yet passed. - PENDING_DEBIT: Funds from this record have already been deducted from the available balance. The status moves to `DEBITED` once the operation that produced the debit finalizes. - DEBITED: Funds from this record have been deducted from the available balance. - PAID_OUT: The record has been included in a payout (regular payout) or made instantly available via a Wix Checking book transfer (Instant Access). Applies to both credits and debits. The only record type bundled into a payout that ends at a different status is `RESERVE_HOLD` (see `DEDUCTED_FROM_PAYOUT`). Check `payoutInfo` versus `bookTransferInfo` to tell them apart. - DEDUCTED_FROM_PAYOUT: A `RESERVE_HOLD` record that has been included in a payout. The held amount was subtracted from the payout total instead of being sent to the merchant. Only reserve hold records end at this status; refunds, chargebacks, and other debits in a payout end at `PAID_OUT`. - PAYOUT_REVERSED: Funds from this record were in a payout that has since failed and been reversed. The reversal returns the funds to the available balance. - name: appliedDate | type: string | description: Date and time the balance record was applied to the account balance. Not returned for virtual records. | validation: format date-time - name: payoutAvailabilityDate | type: string | description: Date the balance record becomes available for payout, in `YYYY-MM-DD` format. | validation: format LOCAL_DATE - name: createdDate | type: string | description: Date and time the balance record was created. | validation: format date-time - name: updatedDate | type: string | description: Date and time the balance record was last updated. | validation: format date-time - name: paymentInfo | type: PaymentInfo | description: Information about the payment that produced this balance record. Returned for records related to a payment, refund, or chargeback. - name: transactionId | type: string | description: GUID of the Wix Payments transaction that produced this balance record. | validation: format GUID - name: createdDate | type: string | description: Date and time the underlying payment was created. | validation: format date-time - name: externalTransactionId | type: string | description: External transaction GUID supplied by the merchant's order system, if any. | validation: maxLength 100 - name: externalOrderId | type: string | description: External order GUID supplied by the merchant's order system, if any. | validation: maxLength 100 - name: externalDisplayOrderId | type: string | description: Display-friendly external order GUID, suitable for showing in a UI. | validation: maxLength 100 - name: externalOrderLink | type: string | description: Link to the order in the merchant's external order management system. | validation: maxLength 1000 - name: customerName | type: string | description: Customer's name as captured by the payment flow. | validation: maxLength 1000 - name: cardHolderName | type: string | description: Cardholder's name as captured at payment time. | validation: maxLength 1000 - name: payoutInfo | type: PayoutInfo | description: Information about the payout that includes this balance record. Returned only after the record has been included in a payout. The presence of `payoutInfo` (versus `bookTransferInfo`) distinguishes a regular payout from an Instant Access book transfer. - name: payoutId | type: string | description: GUID of the payout that this balance record belongs to. | validation: format GUID - name: createdDate | type: string | description: Date and time the payout was created. Returned only for payouts that have already occurred, not those that are scheduled. | validation: format date-time - name: reserveInfo | type: ReserveInfo | description: Reserve details for this balance record. Returned for records with `recordType` `RESERVE_HOLD` or `RESERVE_RELEASE`. - name: hold | type: PayoutInfo | description: Payout details for the hold portion of the reserve, where funds are removed from the available balance. - name: release | type: PayoutInfo | description: Payout details for the release portion of the reserve, where funds are returned to the available balance. - name: reserveHistoryItems | type: array | description: History of changes applied to this reserve, ordered by event time. | validation: maxItems 100 - name: releaseDate | type: string | description: Date the reserve was scheduled to be released, in `YYYY-MM-DD` format. | validation: format LOCAL_DATE - name: createdDate | type: string | description: Date and time the reserve was created. | validation: format date-time - name: reserveType | type: ReserveType | description: Reserve type that determines how the reserve was created. - enum: - ONE_TIME: Reserve that was created manually for a 1-time event. - ROLLING: Reserve that was created automatically by an active reserve policy on the account. - name: bookTransferInfo | type: BookTransferInfo | description: Book transfer details for this balance record. Returned for records funded through a Wix Checking book transfer (Instant Access) rather than a payout. Funds backed by a book transfer are immediately available in the merchant's Wix Checking account. - name: bookTransferId | type: string | description: GUID of the book transfer that funded this balance record. | validation: format GUID - name: transactionReference | type: string | description: External reference for the book transfer transaction. | validation: maxLength 100 - name: createdDate | type: string | description: Date and time the funds became instantly available through the book transfer. | validation: format date-time - name: metadata | type: PagingMetadata | description: Paging metadata for the response. - name: count | type: integer | description: Number of items returned in the response. | validation: format int32 - name: offset | type: integer | description: Offset that was requested. | validation: format int32 - name: total | type: integer | description: Total number of items that match the query. | validation: format int32 - name: tooManyToCount | type: boolean | description: Flag that indicates the server failed to calculate the `total` field. - name: summary | type: BalanceRecordsSummary | description: Aggregated summary across the records that matched the query. Returned only when `includeSummary` is `true`. - name: total | type: Money | description: Net total across all matched records. - name: totalAmount | type: Money | description: Gross total across all matched records, before fees. - name: totalFees | type: Money | description: Total fees across all matched records. - name: totalNet | type: Money | description: Total net amount across all matched records, equivalent to `total`. - name: items | type: array | description: Per-category breakdown of the aggregated records. | validation: maxItems 100 - name: summaryItemType | type: BalanceRecordsSummaryItemType | description: Category of records aggregated by this item. - enum: - UNKNOWN: Unknown summary item type. - CREDITS: All payments from buyers to the account. - REFUNDS: All refunds issued to buyers. - CHARGEBACKS: All chargebacks and chargeback fees. - RESERVE_HOLDS: All reserve holds. - RESERVE_RELEASES: All reserve releases. - FUNDS_ADDED: All top-ups into the account. - FUNDS_TRANSFERRED: All transfers between accounts. - CAPITAL: All Wix Capital movements, including cash advances, automatic remittances, and adjustments. - name: amount | type: Money | description: Gross amount for this category, before fees. - name: fees | type: Money | description: Total fees for this category. - name: net | type: Money | description: Net amount for this category, after fees. ``` ### Examples ### Query the balance records included in a payout Retrieves the balance records stamped with a specific payout ID, with an aggregated summary of the matched records. ```curl curl -X POST \ 'https://www.wixapis.com/wixpay-balances/v5/balance-records/query' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -d '{ "accountId": "50359182-20a7-463a-b069-af9d8b60be5f", "query": { "filter": { "payout_id": "9f7e957d-0def-48c1-8283-5ac0dfe7d986" }, "sort": [ { "fieldName": "applied_date", "order": "ASC" } ], "paging": { "limit": 3, "offset": 0 } }, "includeSummary": true }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.payments.balanceRecords.queryBalanceRecords(accountId, options) Description: Retrieves a list of up to 1000 balance records, given the provided paging, filtering, and sorting. Query Balance Records runs with these defaults, which you can override: - `query.sort[0].fieldName` is `applied_date` in `ASC` order - `query.paging.limit` is `20` - `query.paging.offset` is `0` (and `offset` is required when `paging` is set) Filter and sort field names inside `query` must be **snake_case**. They're read from the `query.filter` object and aren't auto-converted. Supported filter fields: `account_profile_id`, `tags`, `payout_id`, `transaction_id`, `types`, and the date ranges `transaction_creation_date`, `paid`, and `created_date`. Any other field returns an `Unsupported query: unknown parameter ` error. GUID fields accept a single value by equality, `tags` and `types` accept `$in`, and date-range fields accept `$gte` and `$lt`. Supported `sort[i].fieldName` values: `applied_date`, `payment_info.created_date`, `created_date`. At most 1 sort field is allowed. To list every balance record in a payout, filter by `payout_id`. To learn about working with Query methods, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md), [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md), and [Field Projection](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-field-projection.md). # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: accountId Method parameters: param name: accountId | type: string | description: GUID of the Wix Payments account that owns the balance records. Retrieve account GUIDs from the Accounts API. | required: true | validation: format GUID param name: options | type: QueryBalanceRecordsOptions none - name: query | type: Query | description: Query object that supports filtering, sorting, and paging. Filter and sort field names must be **snake_case**. They're read from the `filter` object and aren't auto-converted. Supported filter fields: `account_profile_id`, `tags`, `payout_id`, `transaction_id`, `types`, and the date ranges `transaction_creation_date`, `paid`, and `created_date`. Any other field returns an `Unsupported query: unknown parameter ` error. GUID fields accept a single value by equality, `tags` and `types` accept `$in`, and date-range fields accept `$gte` and `$lt`. Supported `sort[i].fieldName` values: `applied_date`, `payment_info.created_date`, `created_date`. At most 1 sort field is allowed. - name: filter | type: Value | description: Filter object in the following format: `"filter" : { "fieldName1": "value1", "fieldName2":{"$operator":"value2"} }` Example of operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, `$contains` - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: values | type: array | description: - name: sort | type: array | description: Sort object in the following format: `[{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]` - name: fieldName | type: string | description: Name of the field to sort by. | validation: maxLength 512 - name: order | type: SortOrder | description: Sort order. - enum: ASC, DESC - name: origin | type: AddressLocation | description: Origin point for geo-distance sorting on a GEO field results are ordered by distance from this point (ASC = nearest first, DESC = farthest first). - name: latitude | type: number | description: Address latitude. - name: longitude | type: number | description: Address longitude. - name: paging | type: Paging | description: Paging options to limit and skip the number of items. - name: limit | type: integer | description: Number of items to load. | validation: minimum 0, format int32 - name: offset | type: integer | description: Number of items to skip in the current sort order. | validation: minimum 0, format int32 - name: fields | type: array | description: Array of projected fields. A list of specific field names to return. If `fieldsets` are also specified, the union of `fieldsets` and `fields` is returned. - name: fieldsets | type: array | description: Array of named, predefined sets of projected fields. A array of predefined named sets of fields to be returned. Specifying multiple `fieldsets` will return the union of fields from all sets. If `fields` are also specified, the union of `fieldsets` and `fields` is returned. - name: includeSummary | type: boolean | description: Whether to include the aggregated `summary` in the response. When `true`, totals are computed across the records that matched the query (not across the whole account) and returned in `summary`. Default: `false` - name: excludeTotal | type: boolean | description: Whether to omit the total record count from `metadata.total`. Omitting the total can improve performance on large result sets. Default: `false` Return type: PROMISE - name: records | type: array | description: Retrieved balance records. | validation: maxItems 1000 - name: _id | type: string | description: Balance record GUID. Not returned for virtual records produced by `ESTIMATED_RESERVE_HOLD` or `ESTIMATED_RESERVE_RELEASE` tags. | validation: format GUID - name: accountId | type: string | description: GUID of the Wix Payments account this balance record belongs to. | validation: format GUID - name: accountProfileId | type: string | description: GUID of the Wix Payments account profile this balance record belongs to. | validation: format GUID - name: amount | type: Money | description: Gross amount of the balance record, including fees. Positive for credits to the account, negative for deductions. - name: value | type: string | description: Monetary amount. Decimal string with a period as a decimal separator (e.g., 3.99). Optionally, a single (-), to indicate that the amount is negative. | validation: format DECIMAL_VALUE - name: currency | type: string | description: Currency code. Must be valid ISO 4217 currency code (e.g., USD). | validation: format CURRENCY - name: formattedValue | type: string | description: Monetary amount. Decimal string in local format (e.g., 1 000,30). Optionally, a single (-), to indicate that the amount is negative. - name: fee | type: Money | description: Fee that Wix Payments collected on this balance record. - name: net | type: Money | description: Net amount of the balance record after subtracting `fee`. - name: recordType | type: BalanceRecordType | description: Type of the balance record. Describes what kind of money movement this record represents. - enum: - UNKNOWN: Unknown balance record type. - CREDIT: Payment from a buyer for a sale, credited to the merchant's Wix Payments account. - REFUND: Refund issued back to a buyer. - CHARGEBACK: Chargeback initiated by a buyer against a previous payment. - REFUND_REVERSAL: Reversal of a previously issued refund. - CHARGEBACK_REVERSAL: Reversal of a previously issued chargeback. - RESERVE_HOLD: Funds withheld from the available balance as part of a reserve. - RESERVE_RELEASE: Funds returned to the available balance from a previously held reserve. - TOPUP: Transfer of funds from the merchant's external account into their Wix Payments account. - CREDIT_FAILED: Failure on a previously credited payment, resulting in a deduction from the balance. - CHARGEBACK_FEE: Fee charged for processing a chargeback. - CHARGEBACK_FEE_REVERSAL: Reversal of a previously charged chargeback fee. - CAPITAL_CASH_ADVANCE: Cash advance disbursed to the merchant from Wix Capital. - CAPITAL_AUTOMATIC_REMITTANCE: Automatic remittance taken from sales to repay a Wix Capital cash advance. - CAPITAL_ADJUSTMENT: Adjustment applied to a Wix Capital cash advance balance. - name: recordStatus | type: BalanceRecordStatus | description: Current effect of this record on the account balance. The value depends on the record's `recordType`, whether it has a `payoutInfo` or `bookTransferInfo`, and its `payoutAvailabilityDate`. This field is returned on responses only and can't be passed as a filter on list or query requests. To filter by effect on the balance, use `tags` instead. - enum: - UNKNOWN: Unknown balance record status. - PENDING_CREDIT: Funds from this record are added to the available balance once they settle. They aren't yet part of the available balance. - CREDITED: Funds from this record are part of the available balance. - RESERVED: Funds from this record are held in reserve and aren't part of the available balance. Applied to `RESERVE_HOLD` records, and to `RESERVE_RELEASE` records whose `payoutAvailabilityDate` hasn't yet passed. - PENDING_DEBIT: Funds from this record have already been deducted from the available balance. The status moves to `DEBITED` once the operation that produced the debit finalizes. - DEBITED: Funds from this record have been deducted from the available balance. - PAID_OUT: The record has been included in a payout (regular payout) or made instantly available via a Wix Checking book transfer (Instant Access). Applies to both credits and debits. The only record type bundled into a payout that ends at a different status is `RESERVE_HOLD` (see `DEDUCTED_FROM_PAYOUT`). Check `payoutInfo` versus `bookTransferInfo` to tell them apart. - DEDUCTED_FROM_PAYOUT: A `RESERVE_HOLD` record that has been included in a payout. The held amount was subtracted from the payout total instead of being sent to the merchant. Only reserve hold records end at this status; refunds, chargebacks, and other debits in a payout end at `PAID_OUT`. - PAYOUT_REVERSED: Funds from this record were in a payout that has since failed and been reversed. The reversal returns the funds to the available balance. - name: appliedDate | type: Date | description: Date and time the balance record was applied to the account balance. Not returned for virtual records. - name: payoutAvailabilityDate | type: string | description: Date the balance record becomes available for payout, in `YYYY-MM-DD` format. | validation: format LOCAL_DATE - name: _createdDate | type: Date | description: Date and time the balance record was created. - name: _updatedDate | type: Date | description: Date and time the balance record was last updated. - name: paymentInfo | type: PaymentInfo | description: Information about the payment that produced this balance record. Returned for records related to a payment, refund, or chargeback. - name: transactionId | type: string | description: GUID of the Wix Payments transaction that produced this balance record. | validation: format GUID - name: _createdDate | type: Date | description: Date and time the underlying payment was created. - name: externalTransactionId | type: string | description: External transaction GUID supplied by the merchant's order system, if any. | validation: maxLength 100 - name: externalOrderId | type: string | description: External order GUID supplied by the merchant's order system, if any. | validation: maxLength 100 - name: externalDisplayOrderId | type: string | description: Display-friendly external order GUID, suitable for showing in a UI. | validation: maxLength 100 - name: externalOrderLink | type: string | description: Link to the order in the merchant's external order management system. | validation: maxLength 1000 - name: customerName | type: string | description: Customer's name as captured by the payment flow. | validation: maxLength 1000 - name: cardHolderName | type: string | description: Cardholder's name as captured at payment time. | validation: maxLength 1000 - name: payoutInfo | type: PayoutInfo | description: Information about the payout that includes this balance record. Returned only after the record has been included in a payout. The presence of `payoutInfo` (versus `bookTransferInfo`) distinguishes a regular payout from an Instant Access book transfer. - name: payoutId | type: string | description: GUID of the payout that this balance record belongs to. | validation: format GUID - name: _createdDate | type: Date | description: Date and time the payout was created. Returned only for payouts that have already occurred, not those that are scheduled. - name: reserveInfo | type: ReserveInfo | description: Reserve details for this balance record. Returned for records with `recordType` `RESERVE_HOLD` or `RESERVE_RELEASE`. - name: hold | type: PayoutInfo | description: Payout details for the hold portion of the reserve, where funds are removed from the available balance. - name: release | type: PayoutInfo | description: Payout details for the release portion of the reserve, where funds are returned to the available balance. - name: reserveHistoryItems | type: array | description: History of changes applied to this reserve, ordered by event time. | validation: maxItems 100 - name: releaseDate | type: string | description: Date the reserve was scheduled to be released, in `YYYY-MM-DD` format. | validation: format LOCAL_DATE - name: _createdDate | type: Date | description: Date and time the reserve was created. - name: reserveType | type: ReserveType | description: Reserve type that determines how the reserve was created. - enum: - ONE_TIME: Reserve that was created manually for a 1-time event. - ROLLING: Reserve that was created automatically by an active reserve policy on the account. - name: bookTransferInfo | type: BookTransferInfo | description: Book transfer details for this balance record. Returned for records funded through a Wix Checking book transfer (Instant Access) rather than a payout. Funds backed by a book transfer are immediately available in the merchant's Wix Checking account. - name: bookTransferId | type: string | description: GUID of the book transfer that funded this balance record. | validation: format GUID - name: transactionReference | type: string | description: External reference for the book transfer transaction. | validation: maxLength 100 - name: _createdDate | type: Date | description: Date and time the funds became instantly available through the book transfer. - name: metadata | type: PagingMetadata | description: Paging metadata for the response. - name: count | type: integer | description: Number of items returned in the response. | validation: format int32 - name: offset | type: integer | description: Offset that was requested. | validation: format int32 - name: total | type: integer | description: Total number of items that match the query. | validation: format int32 - name: tooManyToCount | type: boolean | description: Flag that indicates the server failed to calculate the `total` field. - name: summary | type: BalanceRecordsSummary | description: Aggregated summary across the records that matched the query. Returned only when `includeSummary` is `true`. - name: total | type: Money | description: Net total across all matched records. - name: totalAmount | type: Money | description: Gross total across all matched records, before fees. - name: totalFees | type: Money | description: Total fees across all matched records. - name: totalNet | type: Money | description: Total net amount across all matched records, equivalent to `total`. - name: items | type: array | description: Per-category breakdown of the aggregated records. | validation: maxItems 100 - name: summaryItemType | type: BalanceRecordsSummaryItemType | description: Category of records aggregated by this item. - enum: - UNKNOWN: Unknown summary item type. - CREDITS: All payments from buyers to the account. - REFUNDS: All refunds issued to buyers. - CHARGEBACKS: All chargebacks and chargeback fees. - RESERVE_HOLDS: All reserve holds. - RESERVE_RELEASES: All reserve releases. - FUNDS_ADDED: All top-ups into the account. - FUNDS_TRANSFERRED: All transfers between accounts. - CAPITAL: All Wix Capital movements, including cash advances, automatic remittances, and adjustments. - name: amount | type: Money | description: Gross amount for this category, before fees. - name: fees | type: Money | description: Total fees for this category. - name: net | type: Money | description: Net amount for this category, after fees. ``` ### Examples ### Query the balance records included in a payout Retrieves the balance records stamped with a specific payout ID, with an aggregated summary of the matched records. ```javascript import { balanceRecords } from "@wix/payments"; const accountId = "50359182-20a7-463a-b069-af9d8b60be5f"; const options = { query: { filter: { payout_id: "9f7e957d-0def-48c1-8283-5ac0dfe7d986", }, sort: [ { fieldName: "applied_date", order: "ASC", }, ], paging: { limit: 3, offset: 0, }, }, includeSummary: true, }; async function queryBalanceRecords() { const response = await balanceRecords.queryBalanceRecords(accountId, options); } /* Promise resolves to: * { * "records": [ * { * "_id": "c3e48d2b-078b-4541-999c-27312b218a01", * "accountId": "50359182-20a7-463a-b069-af9d8b60be5f", * "accountProfileId": "e61abb81-9047-45fe-b9f8-303fd0d51dd9", * "amount": { * "value": "60.00", * "currency": "USD" * }, * "fee": { * "value": "3.50", * "currency": "USD" * }, * "net": { * "value": "56.50", * "currency": "USD" * }, * "recordType": "CREDIT", * "recordStatus": "PAID_OUT", * "appliedDate": "2024-04-26T19:16:26Z", * "payoutAvailabilityDate": "2024-04-27", * "_createdDate": "2024-04-26T03:35:40.578Z", * "_updatedDate": "2024-04-26T21:06:18.984Z", * "paymentInfo": { * "transactionId": "9c6bafce-1e6f-4758-9542-41b5f3e0c184", * "createdDate": "2024-04-26T03:35:37.559Z", * "externalTransactionId": "9c6bafce-1e6f-4758-9542-41b5f3e0c184", * "customerName": "John Doe", * "cardHolderName": "John Doe" * }, * "payoutInfo": { * "payoutId": "9f7e957d-0def-48c1-8283-5ac0dfe7d986", * "createdDate": "2024-05-06T12:39:34.639Z" * } * }, * { * "_id": "db7ee82c-f847-43d8-b8b8-3b8411eed59a", * "accountId": "50359182-20a7-463a-b069-af9d8b60be5f", * "accountProfileId": "e61abb81-9047-45fe-b9f8-303fd0d51dd9", * "amount": { * "value": "60.00", * "currency": "USD" * }, * "fee": { * "value": "3.50", * "currency": "USD" * }, * "net": { * "value": "56.50", * "currency": "USD" * }, * "recordType": "CREDIT", * "recordStatus": "PAID_OUT", * "appliedDate": "2024-04-28T21:17:58Z", * "payoutAvailabilityDate": "2024-04-30", * "_createdDate": "2024-04-26T14:06:14.410Z", * "_updatedDate": "2024-04-28T23:35:39.286Z", * "paymentInfo": { * "transactionId": "be12689b-ebbe-444e-b02b-70e9b84d0dc4", * "createdDate": "2024-04-26T14:06:11.907Z", * "externalTransactionId": "be12689b-ebbe-444e-b02b-70e9b84d0dc4", * "customerName": "Jane Smith", * "cardHolderName": "Jane Smith" * }, * "payoutInfo": { * "payoutId": "9f7e957d-0def-48c1-8283-5ac0dfe7d986", * "createdDate": "2024-05-06T12:39:34.901Z" * } * } * ], * "metadata": { * "count": 3, * "offset": 0, * "total": 12 * }, * "summary": { * "total": { * "value": "725.34", * "currency": "USD" * }, * "totalAmount": { * "value": "770.00", * "currency": "USD" * }, * "totalFees": { * "value": "44.66", * "currency": "USD" * }, * "totalNet": { * "value": "725.34", * "currency": "USD" * }, * "items": [ * { * "summaryItemType": "CREDITS", * "amount": { * "value": "770.00", * "currency": "USD" * }, * "fees": { * "value": "44.66", * "currency": "USD" * }, * "net": { * "value": "725.34", * "currency": "USD" * } * } * ] * } * } */ ``` ### queryBalanceRecords (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { balanceRecords } from '@wix/payments'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { balanceRecords }, // Include the auth strategy and host as relevant }); async function queryBalanceRecords(accountId,options) { const response = await myWixClient.balanceRecords.queryBalanceRecords(accountId,options); }; ``` ---