The WooPayments Balance report summarizes starting balance, charges, fees, refunds, disputes, payouts, and ending balance for a UTC period. A payout contains only transactions eligible for that payout schedule, and a bank can post it on another date. Comparing the report ending balance directly with one deposit creates a false variance before pending and reserved funds are considered.
Use this when WooPayments or Stripe-backed payment activity seems correct at the order level but the report ending balance, payout statement, and bank deposit differ.
Quick answer
Align all reports to UTC, identify the payout cutoff and availability date, then bridge ending balance to payout using pending funds, reserves, refunds, disputes, fees, adjustments, and payouts in transit. Only the residual after that timing bridge is an unexplained variance that needs row-level investigation.
What to check first
- Capture starting and ending balance, report period, account time zone, payout ID, expected arrival, and bank posting date.
- Separate transactions created in the period from funds that became available in the period.
- List pending amounts, rolling reserves, disputes, refunds, fees, and manual adjustments with transaction IDs.
- Tie the payout statement to the bank deposit net of any bank-side fees or currency conversion.
- Recalculate the bridge and investigate only rows that remain outside the documented timing and classification rules.
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Freeze the Balance report, payout detail, transaction export, and bank statement used for the comparison. | Capture starting and ending balance, report period, account time zone, payout ID, expected arrival, and bank posting date. | The report equation from starting balance through activity to ending balance recalculates exactly. |
| Normalize timestamps to UTC and add separate availability and bank-posting dates. | Separate transactions created in the period from funds that became available in the period. | The payout detail ties to the provider payout amount and the bank deposit or open cash clearing item. |
| Build the timing and classification bridge from ending balance to payout and cash clearing. | List pending amounts, rolling reserves, disputes, refunds, fees, and manual adjustments with transaction IDs. | Every bridge line has an ID, amount, currency, timestamp, source, status, and owner. |
| Trace residuals to transaction IDs and correct mapping, import, or provider support issues. | Tie the payout statement to the bank deposit net of any bank-side fees or currency conversion. | The next payout can be reconciled with the same rules without manual plug entries. |
Why this usually happens
- Transaction creation, fund availability, payout creation, and bank posting have different timestamps.
- A report period can include balance movements that belong to another order or payout period.
- Finance imports may drop signed transaction types or combine provider and bank fees.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
bridge_item,amount,evidence,status
report_ending_balance,18422.10,balance_report,base
pending_not_in_payout,-420.00,transaction_export,explained
reserve_hold,-21.80,balance_transaction,investigate
payout_in_transit,-17980.30,po_123,clearing
residual,0.00,recalculated,closed
Test scenarios to run
Run the same controlled fixture across these branches. Write down the expected result before testing so a surprising response is easy to identify.
| Scenario | Fixture | Expected result |
|---|
| Weekend cutoff | Friday charges with Monday payout | Funds stay pending until availability and do not force a Friday bank tie |
| Refund after payout | Original charge paid out, refund created later | Refund appears in later balance movement and payout |
| Open dispute | Dispute debit or reserve in period | Variance bridge includes dispute transaction and state |
| Payout in transit | Payout created before bank posting | Provider balance decreases while cash clearing remains open |
Safe fix order
Use a sequence that makes each result easy to prove. Stop when new evidence changes the scope or owner of the problem.
- Freeze the Balance report, payout detail, transaction export, and bank statement used for the comparison.
- Normalize timestamps to UTC and add separate availability and bank-posting dates.
- Build the timing and classification bridge from ending balance to payout and cash clearing.
- Trace residuals to transaction IDs and correct mapping, import, or provider support issues.
- Save the reconciled bridge and repeat the method on the next payout as a control.
Decision rule
Treat a difference as explained only when it has a transaction, payout, reserve, availability, or bank identifier and a clear accounting treatment. A label such as timing difference without row-level evidence is still unresolved.
Production verification checklist
- The report equation from starting balance through activity to ending balance recalculates exactly.
- The payout detail ties to the provider payout amount and the bank deposit or open cash clearing item.
- Every bridge line has an ID, amount, currency, timestamp, source, status, and owner.
- The next payout can be reconciled with the same rules without manual plug entries.
Field notes
- Use a cash-clearing account for payouts in transit rather than forcing the bank balance early.
- Preserve the provider's transaction type and sign before mapping it to a general-ledger account.
- A small residual can still reveal a systematic rounding, FX, or import bug across many payouts.
Questions teams ask during testing
Why can the ending balance be positive after a payout?
Recent funds may still be pending or available for a later payout, and reserves or adjustments may remain in the account.
Should the bank date replace the payout date?
No. Keep provider creation, expected arrival, and bank posting as separate dates.
What is the best join key?
Use payout IDs and balance transaction IDs, with order and charge IDs for business context.
Mistakes to avoid
- Do not compare one payout directly with the whole report ending balance.
- Do not move UTC boundaries to make the totals appear closer.
- Do not hide pending funds or reserves inside generic fees.
- Do not close an unexplained residual only because it is below one payout's materiality threshold.
What to tell the client or owner
Share the account, UTC period, ending balance, payout ID, bank amount, timing bridge, unresolved transaction IDs, residual, materiality policy, and next owner.
When HandL WP should help
Bring in help when this affects leads, checkout, search visibility, security, paid media reporting, or a client production site. HandL WP can trace the issue through WordPress, hosting, cache, tracking, and Search Console, then verify the workflow after the technical fix.
If this is active on a production site, debug a WooPayments payout variance.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references