Finance Dashboard Widget & Drift Auto-Repair
WalletPro adds a wallet health summary to the WordPress admin dashboard and a one-click drift correction button on the Wallet Reports reconciliation screen. Both features are designed for the daily operational glance, without requiring a full report to understand the current state of the wallet program.
Finance Dashboard Widget
Where to find it
Log in to the WordPress admin and go to Dashboard. The Wallet Health widget appears in the standard WordPress dashboard widget grid. Drag it to reposition it. Administrators and shop managers can see it; subscriber-level users cannot.
The five KPIs
| KPI | What it shows |
|---|---|
| Total liability | Sum of all wallet balances across every customer, the amount the store currently owes customers. Computed from the live ledger. |
| Top-ups today | Total customer-funded top-ups credited today (UTC). Resets at midnight UTC. |
| Pending withdrawals | Count of withdrawal requests in pending status. |
| Pending adjustments | Count of manual wallet adjustments waiting in the maker-checker approval queue. |
| Credits today | Total wallet credits of any type recorded today (UTC). Includes cashback, manual credits, refunds to wallet, and top-ups. |
Caching
The KPIs are cached in a WordPress transient named walletpro_dashboard_widget for 5 minutes. This means figures on the widget can lag real-time by up to 5 minutes. The transient is deleted automatically whenever walletpro_funds_recorded fires (i.e. whenever any wallet credit or debit is recorded), so the widget refreshes immediately after any wallet movement.
To force an immediate refresh, save any post or reload the dashboard. The transient will have expired or been busted by the last wallet event.
The 5-minute cache is a performance trade-off. On a very high-volume store with continuous wallet activity, the transient is busted on every walletpro_funds_recorded and the widget shows near-real-time data. On a quiet store, figures may be up to 5 minutes old.
Reconciliation Drift Auto-Repair
What is drift?
Drift occurs when a customer's stored balance (_walletpro_balance usermeta) does not match the sum of their wallet ledger entries. This can happen after a server crash mid-transaction, a database restore from an older backup, or a third-party plugin that writes directly to the usermeta without going through WalletPro's write path.
The Financial Reports screen shows a reconciliation table listing customers with drift, together with their stored balance, ledger sum, and the difference.
The Queue Repair button
Each drifted customer in the reconciliation table has a Queue repair button. Clicking it does not adjust the wallet immediately. Instead, it creates a pending adjustment in the maker-checker queue with the exact bcmath delta needed to bring the stored balance in line with the ledger sum. The pending adjustment then appears on the Manual Adjustments approval queue for a second admin to review and approve.
Drift repair goes through the maker-checker queue to prevent a single admin from silently writing money to a wallet. A second admin must approve the pending adjustment before the balance is corrected. This preserves the audit trail and the money-safety invariant.
How the delta is calculated
The delta is ledger_sum − stored_balance, computed with bcmath at four decimal places. A positive delta means the stored balance is lower than the ledger (the customer is owed money). A negative delta means the stored balance is higher than the ledger (the store issued more balance than ledger entries justify). Both directions are handled.
After repair is approved
Once the pending adjustment is approved, FundsManager applies the delta through its normal write path: a new ledger entry is created, the balance is updated atomically, and an drift_repaired audit log entry is written with the approver's identity and the repair amount.
Hook reference
| Hook | Type | Purpose |
|---|---|---|
| walletpro_dashboard_widget_kpis | Filter | Modify or extend the KPI array before it is rendered. Receives the KPI array; each entry has label and value keys. |
| walletpro_drift_repair_queued | Action | Fires when a repair is queued. Passes ($user_id, $delta). Use to notify a second admin. |