Admin Balances

The Admin Balances screen gives merchants a consolidated view of every customer's wallet balance, with tools to manually credit or debit accounts, apply bulk adjustments, and export balance data for accounting workflows.

Overview

WalletPro maintains a real-time balance ledger for every customer who holds a wallet. The Admin Balances screen (WooCommerce > WalletPro > Balances) surfaces this ledger in a searchable, filterable table. From this screen you can:

• View every customer's current balance, lifetime funded amount, and lifetime spent amount.
• Credit or debit a single customer's wallet with an optional internal reason note.
• Apply a bulk credit or debit to a filtered set of customers.
• Export the full balance table or a filtered subset to CSV for GL reconciliation.
• Drill into a customer's full transaction ledger from the same screen.

Every manual adjustment made from this screen is written to the tamper-evident HMAC-chained audit ledger, which means all entries are attributable to a specific WordPress user and cannot be modified after the fact.

How It Works

When a customer's wallet is created (either at registration, on first top-up, or when an admin issues the first credit), WalletPro creates a ledger account record linked to that user. Each subsequent credit or debit appends an immutable entry to the ledger. The balance shown in the Admin Balances table is computed as the sum of all settled ledger entries for that account.

Manual adjustments from the Admin Balances screen use atomic database transactions. If any part of a debit or credit fails, for example, a debit that would push a balance below zero when the Allow Negative Balances setting is disabled, the entire operation is rolled back and an admin notice is returned. No partial writes occur.

Navigating to Admin Balances

1. Log in to WordPress as a user with the manage_woocommerce capability.
2. Go to WooCommerce > WalletPro > Balances.
3. The balances table loads with all customers who have an active wallet, sorted by balance descending by default.

Balances Table

The table displays the following columns:

Searching and Filtering

Use the search box above the table to find a customer by name, email, or user ID. Additional filters appear in the Filter dropdown:

Manual Credit and Debit

Single Customer Adjustment

1. In the balances table, click Adjust next to the target customer.
2. The adjustment modal opens, showing the customer's current balance.
3. Choose the operation type: Credit or Debit.
4. Enter the amount. For debits, the field validates that the amount does not exceed the current balance unless Allow Negative Balances is on.
5. Select a Reason Code from the dropdown. Reason codes are configurable under WooCommerce > WalletPro > Settings > Reason Codes. Default codes include: Goodwill adjustment, Refund correction, Promotional credit, Data correction, Other.
6. Optionally enter a free-text Internal Note (not visible to the customer, stored in the ledger).
7. Toggle Notify customer by email to send the customer a balance-change notification email using the template configured in WooCommerce > WalletPro > Settings > Emails > Balance Adjusted.
8. Click Apply Adjustment. The modal closes and the table row updates immediately.

Bulk Adjustment

1. Use the search and filter controls to narrow the table to the customers you want to adjust.
2. Check the header checkbox to select all visible rows, or check individual rows.
3. In the Bulk Actions dropdown, select Credit selected wallets or Debit selected wallets.
4. Click Apply. A confirmation dialog shows the number of affected wallets and the total value of the operation.
5. Enter the amount, reason code, and optional note, then confirm.

Bulk adjustments process synchronously for up to 200 customers. For larger sets, WalletPro schedules the adjustments as a background Action Scheduler job and displays a progress notice in the admin. You will receive a summary email when the batch completes.

Viewing a Customer's Ledger

Click Ledger in the Actions column for any customer to open the single-customer ledger view. This page shows every credit and debit on that wallet in reverse-chronological order.

The ledger page includes its own CSV export button, which exports only that customer's ledger entries within an optional date range.

Settings Relevant to Admin Balances

The following settings under WooCommerce > WalletPro > Settings directly affect admin balance behavior:

Exporting Balance Data

Instant CSV Export

1. Apply any filters or search terms to scope the export.
2. Click Export CSV above the table.
3. The download begins immediately. Large exports (over 5,000 rows) are queued as a background job and delivered to your admin email when ready.

The exported CSV includes all visible columns plus two additional columns not shown in the table: Wallet Currency and Account Created Date. Column headers match the display names in the table for straightforward import into spreadsheet or accounting tools.

Scheduled Balance Report

To configure recurring balance emails:

1. Go to WooCommerce > WalletPro > Settings > Reports.
2. Enable Scheduled Balances Report Email.
3. Set the Frequency: Daily, Weekly (choose day of week), or Monthly (choose day of month).
4. Enter one or more recipient email addresses in Report Recipients, separated by commas.
5. Choose whether to include Zero-Balance Wallets in the report.
6. Save settings. The first report will send at the next scheduled interval.

Programmatic Access

Admin balance reads and adjustments are available via the REST API and WP-CLI for automated workflows.

REST API

List all balances (requires manage_woocommerce permission):

# GET /wp-json/walletpro/v1/balances
curl -X GET \
  "https://example.com/wp-json/walletpro/v1/balances?per_page=50&min_balance=10" \
  -H "Authorization: Bearer <token>"

Apply a manual adjustment:

# POST /wp-json/walletpro/v1/wallets/{user_id}/adjust
curl -X POST \
  "https://example.com/wp-json/walletpro/v1/wallets/42/adjust" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "credit",
    "amount": "15.00",
    "currency": "USD",
    "reason_code": "goodwill_adjustment",
    "note": "Compensating for delayed shipment on order #1234",
    "notify_customer": true
  }'

Example response:

{
  "id": 8821,
  "user_id": 42,
  "type": "credit",
  "amount": "15.00",
  "currency": "USD",
  "balance_after": "47.50",
  "reason_code": "goodwill_adjustment",
  "note": "Compensating for delayed shipment on order #1234",
  "actor_id": 1,
  "created_at": "2026-06-20T14:32:00Z",
  "hmac": "a3f9c2..."
}

WP-CLI

# View a customer's current balance
wp wallet balance get --user=42

# Credit a wallet
wp wallet balance credit --user=42 --amount=15.00 --reason="goodwill_adjustment" --note="Order delay"

# Debit a wallet
wp wallet balance debit --user=42 --amount=5.00 --reason="data_correction"

# Export all balances to CSV
wp wallet balances export --format=csv > balances-2026-06-20.csv

# Bulk credit from a CSV file (user_id,amount columns required)
wp wallet balances bulk-credit --file=credits.csv --reason="promotional_credit"

PHP Hook: After Admin Adjustment

Use the walletpro_after_admin_adjustment action to trigger custom logic whenever an admin manually adjusts a balance:

add_action( 'walletpro_after_admin_adjustment', function( $ledger_entry, $user_id, $actor_id ) {
    // $ledger_entry is an associative array of the new ledger row.
    if ( $ledger_entry['type'] === 'credit' && floatval( $ledger_entry['amount'] ) >= 100 ) {
        // Flag large admin credits for secondary review.
        my_flag_large_credit( $user_id, $ledger_entry['amount'] );
    }
}, 10, 3 );

Audit and Compliance

Every ledger entry, including all manual adjustments, is protected by an HMAC chain. Each entry's hash is computed from its content plus the hash of the previous entry, making it detectable if any historical record is modified or deleted at the database level.

To verify the integrity of the ledger at any time, run:

wp wallet doctor --check=ledger-integrity

This command walks the entire ledger chain and reports any broken links. For a specific customer:

wp wallet doctor --check=ledger-integrity --user=42

Output indicates either PASS (all hashes validate) or lists the specific ledger entry IDs where the chain breaks, along with the user ID and timestamp to assist investigation.