Operator guideEN

Merchant Balance / List

Transaction journal for manual merchant-balance entries, with date filtering, pagination, and a separate current-balance summary.

How to use this guide

Start with the main guide

Follow the explanation and examples first. Extra definitions and formulas are available below when you need them.

What this page shows

This page shows the stored merchant-balance transaction history and the current merchant-balance total. Operators use it to review manual debit or credit adjustments and to open the create-only adjustment form when they have create permission.

How to read the page

  • The grid is the journal of manual merchant-balance entries.
  • Type shows whether the row was saved as a DEBIT or CREDIT.
  • Amount is the raw transaction amount of that row. The table does not add a currency code, symbol, or currency conversion label.
  • UserID shows which admin user ID was written into the record when the transaction was created.
  • Created At, Updated, and Deleted are audit timestamps from the transaction table.
  • Merchant balance is the all-time calculated current balance, rounded half-up to two decimals by the source and rendered as an unlabelled number.

Filters and controls

  • Date start and Date end restrict which journal rows are listed. The default values are the browser-local date seven days ago and the browser-local date for tomorrow; the hook sends both as yyyy-MM-dd.
  • Pagination changes only the visible slice of the journal and defaults to 200 rows per page.
  • Create opens the create-only adjustment form. It is disabled when the operator lacks Merchant Balance create permission.

Important caveats

  • The top Merchant balance number is not the sum of visible rows on this page.
  • The date range filters apply to merchantBalanceList, but merchantBalanceTotal is loaded through a separate source formula without the selected dates.
  • The date filter uses the exact start and end values sent by the page and does not expand Date end to the end of that day. Do not assume whole-day inclusion for the selected end date.
  • The total combines manual merchant-balance transactions, wallet balances, successful deposits, and withdrawals in statuses 0, 1, or 5. It is not a simple manual-journal total.
  • Wallet values are divided by currencies.exchange_rate; deposit and withdrawal values are divided by their stored banking conversion rate. This flow does not prove the resulting reporting currency or the timestamp/basis of either rate.
  • Invalid or non-finite source amounts and missing or non-positive required rates fail the current-balance read. The page has no dedicated visible read-error block, so a failed request may leave the previous table or no refreshed data rather than showing a new total.
  • The source sets the session time zone to UTC before reading this report.
  • The list source supports a search query across user id, amount, and type, but the verified list page currently exposes only date filters and pagination.
  • If the operator lacks Merchant Balance read permission, the page shows a no-permission state instead of the table.
  • There are no row-level edit or delete actions in the current CRM surface.
More details

Definitions and formulas

Open only the section you need. The relevant section opens automatically when you request help for a specific item on screen.

Calculations11 topicsOpen details

Default date range

The default journal view is a recent window, not all historical rows.

Inputs
current browser date, NUMBER_OF_DAYS_BEFORE
Formula
The list initializes Date start to 7 days before the current browser date and Date end to tomorrow.

Request date format

Date pickers drive day-level source filtering for journal rows.

Inputs
Date start, Date end
Formula
The hook formats startDate and endDate as yyyy-MM-dd before requesting merchant-balance data.

Journal pagination

Pagination changes only which journal rows are visible.

Inputs
pageNo, limit, row count
Formula
The shared pagination helper initializes pageNo to 1 and limit to 200. The source converts page and limit to a result slice and returns the matching row count separately.

Journal date filter

Date filters apply to transaction rows, not to the current balance total.

Inputs
startDate, endDate, merchant_balance_transactions.created_at
Formula
The SQL applies created_at >= startDate and created_at <= endDate when those values are supplied.
Caveats
The hook sends date-only `yyyy-MM-dd` strings., The page does not expand Date end to an end-of-day timestamp; the exact stored-date comparison defines the boundary.

Source-supported search

Search exists in the source contract, but the verified list page currently does not render a search box for this page.

Inputs
search, user id, amount, type
Formula
The source can search user id, amount, and transaction type when a search value is supplied.

Journal sort

Newer journal rows appear first by default.

Inputs
sortField, sortDirection, created_at
Formula
The service defaults to created_at and DESC. The SQL accepts amount or type as alternate sort fields and otherwise orders by created_at.

Merchant balance total

The Merchant balance summary is a current all-time balance formula, not a sum of visible journal rows.

Inputs
manual merchant-balance transactions, wallet balances, successful deposits, withdrawals in statuses 0, 1, or 5
Formula
The current balance sums each manual row as amount for CREDIT or negative amount for DEBIT, subtracts wallet balances normalized by currency exchange rate, adds successful deposits normalized by conversion rate, and subtracts withdrawals in statuses 0, 1, or 5 normalized by conversion rate.
Caveats
The visible result has no currency code or symbol., The flow does not define reporting currency, rate source ownership, or rate timestamp.

Total rounding

The displayed summary is rounded to two decimals before it reaches the page.

Inputs
merchant balance source result
Formula
The normalizer parses merchant_balance as Decimal, rounds to two decimal places with ROUND_HALF_UP, and returns a fixed two-decimal string.

Total source validation

The report fails rather than presenting a partially normalized total or silently substituting zero.

Inputs
merchant balance source result, invalid amount diagnostics, missing or non-positive exchange rates, missing or non-positive conversion rates
Formula
The SQL exposes invalid-input diagnostics, and the normalizer throws when any diagnostic is non-zero or the calculated balance is not finite.

Read timezone

Backend timestamp comparisons run in a UTC database session, while default picker dates originate in the browser.

Inputs
database session
Formula
The service executes SET TIME ZONE 'UTC' before the journal, count, and total queries.

Permission gating

Seeing the page and creating a manual adjustment are separate permission checks.

Inputs
MerchantBalance read permission, MerchantBalance create permission
Formula
The page shows a no-permission state without read permission and disables Create without create permission; the corresponding requests enforce those access checks.
Columns7 topicsOpen details

Id

Internal identifier of the journal row.

Visual Type
grid-column

Type

Whether the manual transaction was stored as `DEBIT` or `CREDIT`.

Visual Type
badge

Amount

Amount written into the manual merchant-balance transaction row.

Visual Type
amount
Caveats
CREDIT contributes the stored amount and DEBIT contributes its negative; a negative stored amount reverses the normal type direction., The table renders the raw value without a currency code, symbol, or formatter.

UserID

Admin user ID attached to the transaction record.

Visual Type
grid-column

Created At

Timestamp when the transaction row was first created.

Visual Type
datetime

Updated

Timestamp of the last backend update on the row.

Visual Type
datetime

Deleted

Soft-delete timestamp if the row was removed outside this screen.

Visual Type
datetime
Caveats
The verified list page has no row-level delete action.
Fields3 topicsOpen details

No Permission

Shown instead of the journal when the operator lacks Merchant Balance read permission.

Group
access-state
Visual Type
empty-state

Merchant Balance

Identifies the manual merchant-balance journal workspace.

Group
header
Visual Type
heading

Create

Opens the create-only manual adjustment form when the operator has create permission.

Group
header
Visual Type
button
Caveats
The button is disabled when the operator lacks Merchant Balance create permission.
Filters3 topicsOpen details

Date start

Lower bound for the journal query.

Visual Type
date-filter
Default Value
7 days before the current browser date
Caveats
The hook serializes the browser date as `yyyy-MM-dd`., The SQL applies `created_at >= startDate`; database timestamp coercion defines the exact boundary.

Date end

Upper bound for the journal query.

Visual Type
date-filter
Default Value
tomorrow from the current browser date
Caveats
The hook serializes the browser date as `yyyy-MM-dd`., The date comparison applies `created_at <= endDate`; the page does not expand the value to an end-of-day timestamp.

Pagination

Controls which slice of matching journal rows is visible.

Visual Type
pagination
Default Value
page 1, 200 rows per page
Metrics1 topicOpen details

Merchant balance

Current all-time balance formula returned independently from the date-filtered journal rows.

Aliases
current merchant balance, merchant balance summary
Formula
Manual rows with CREDIT contributing amount and DEBIT contributing negative amount, minus wallets divided by stored currency exchange rates, plus successful deposits divided by their banking conversion rates, minus withdrawals in statuses 0, 1, or 5 divided by their banking conversion rates.
Filter Dependencies
Start Date: ignored by this metric | End Date: ignored by this metric | Pagination: ignored by this metric
Timezone Basis
The service sets the database session to UTC, but the total query is not date-scoped.
Currency Basis
Not defined by the verified flow; the UI renders no currency code or symbol.
Exchange Rate Basis
Uses current stored currencies.exchange_rate and per-transaction conversion_rate values selected by the SQL; rate ownership and timestamps are not exposed here.
Rounding Rule
Decimal ROUND_HALF_UP to two places, returned as a fixed two-decimal string.
Missing Rate Behavior
Missing or non-positive required rates fail the read; no zero substitution is used.
Refund Reversal Handling
Not separately identified by this formula; withdrawals are included only by statuses 0, 1, and 5, and deposits only by successful status.
Display Rule
Raw fixed-decimal text; green only when numerically greater than zero, otherwise red; a falsy total is not rendered.
Caveats
This is not the sum of visible journal rows., Do not describe it as EUR, USD, base currency, or another reporting currency without separate verified evidence.
More help

Related pages

Actions / Merchant Balance

Operator workspace for reviewing the merchant-balance transaction journal and creating manual debit or credit adjustments.

Merchant Balance / Form

Create-only form for posting a manual debit or credit transaction into the merchant-balance journal.

Activity Tag Rules / List

Main inventory for activity-driven tag rules, with search, activity and status filters, grouped rows, clone, edit, and run actions.

Affiliate Deals / List

Searchable table of affiliate deal rows with PID filter, create action, dashboard shortcut, and edit/delete row actions.

Affiliate Payment Settings / List

Affiliate payment settings inventory page for reviewing configured rows and opening saved records.

Affiliate Settings / List

Affiliate inventory list used to review saved affiliates and open detail or report flows.