Elite Balance ships WP-CLI commands for scripted work: checking and adjusting balances, migrating from another wallet plugin, copying the old plugin’s history, proving the ledger’s arithmetic, and working the withdrawals queue on payout day. This page lists every command and option in version 1.1.0 with examples. It is written for developers and site administrators who are comfortable with a terminal and WP-CLI.
Before you start
↑ Back to top- All commands live under
wp rb-elbal. Runwp help rb-elbal(orwp help rb-elbal <command>) to see the built-in help. - The commands are registered only while Elite Balance is active and its requirements are met.
- Every command goes through the same services as the admin screens, so the same guarantees apply: each write is idempotent, debits never exceed the available balance, and nothing edits history.
- A user can be given as a user ID or an email address wherever a command takes
<user>. - Amounts are positive decimals with at most four decimal places, for example
25,25.50or9.9900. Balances print in that four-decimal form (25.5000). - A failing command prints
Error: ...and exits with status 1, so scripts and monitoring can check the exit code.
Important: Back up your database before running migrate or a large batch of credit or debit commands. Ledger rows are never deleted; a wrong adjustment is corrected with a new, opposite one.
Command summary
↑ Back to top| Command | What it does |
|---|---|
wp rb-elbal balance <user> | Prints a customer’s balance and available balance. |
wp rb-elbal credit <user> <amount> | Credits a wallet (creates it if needed). |
wp rb-elbal debit <user> <amount> | Debits a wallet. |
wp rb-elbal migrate [<source>] | Imports balances from another wallet plugin and prints the reconciliation report. |
wp rb-elbal reconcile | Checks every wallet against its own transaction history. |
wp rb-elbal expire-holds | Releases pending holds whose expiry time has passed. |
wp rb-elbal history copy [<source>] | Copies an old wallet plugin’s log into the earlier history archive. New in 1.1.0. |
wp rb-elbal history status | Shows the archive and copy status per source. New in 1.1.0. |
wp rb-elbal withdrawals list | Lists withdrawal requests. |
wp rb-elbal withdrawals show <id> | Shows one request in full, payout details included. |
wp rb-elbal withdrawals transfer <id> | Marks a request transferred and debits the wallet. |
wp rb-elbal withdrawals reject <id> | Rejects a request and releases the reserved funds. |
Balances
↑ Back to topbalance
↑ Back to topPrints the customer’s ledger balance and the available balance (the balance minus pending holds, which is what checkout and withdrawals can use).
| Argument | Required | Description |
|---|---|---|
<user> | Yes | User ID or email address. |
$ wp rb-elbal balance 42
Balance: 54.0000
Available: 24.0000
$ wp rb-elbal balance customer@example.comcredit and debit
↑ Back to topAdds funds to or removes funds from a wallet. Both write an Admin adjustment transaction, which the customer sees as “Balance adjustment” on their wallet page.
| Argument or option | Required | Description |
|---|---|---|
<user> | Yes | User ID or email address. |
<amount> | Yes | Positive amount, at most four decimal places. |
--note=<note> | No, strongly recommended | The reason, stored on the ledger row and shown to staff. Never shown to the customer. |
--key=<key> | No | A deterministic idempotency key, 1 to 191 characters. When omitted, a unique key is generated for each run. |
wp rb-elbal credit 42 25.00 --note="Goodwill for late delivery" --key="goodwill:order-8817"
wp rb-elbal debit 42 10.00 --note="Correction of duplicate credit" --key="fix:2026-07-09:user42"On success the command prints the transaction ID, the amount and the new balance:
Success: Transaction #318: credited 25.0000. Balance is now 79.0000.What to know:
- Use
--keywhenever the command could run more than once (cron jobs, deploy scripts, retried loops). Running the same key again changes nothing and printsWarning: Idempotency replay: transaction #318 already existed. Balance unchanged.Without a key, every run is a new operation and moves money again. Build keys from your own stable identifiers, never from timestamps. - A credit creates the wallet if the customer has none, and works on locked wallets.
- A debit fails when the customer has no wallet, when the wallet is locked, or when the amount is more than the available balance. Errors print as
Error: [rb_elbal_insufficient_funds] ...,Error: [rb_elbal_wallet_locked] ...and so on. - These commands do not record a staff member, so the transaction’s Reference column has no “By …” name, even if you pass WP-CLI’s global
--useroption. Use--noteto say who ran it and why. - The Wallet credited or Wallet debited email is sent if that email is enabled under WooCommerce > Settings > Emails. There is no option to silence it per command; to adjust silently, use the admin form with Email the customer unticked, or the
rb_elbal_credit()function with'meta' => array( 'notify' => 'no' )(see Developer Reference).
Migration
↑ Back to topmigrate
↑ Back to topImports customer balances from another wallet plugin into the ledger, in the same process (no background queue), and prints the reconciliation report. It is re-runnable: each customer’s balance imports at most once, so a second run only picks up what is missing. The source plugin’s data is never changed or deleted. The admin equivalent is the Migration section of WooCommerce > Elite Balance > Tools; see Migrating from Another Wallet Plugin.
| Argument or option | Required | Description |
|---|---|---|
[<source>] | No | The source ID (below). Default: wps. |
--deactivate | Yes, while the source plugin is active | Deactivates the source plugin first (plain deactivation, its data is kept). An active source plugin could change balances during the import, so the command refuses to run without this flag while it is active. |
--yes | No | Skips the confirmation prompt. |
Source IDs:
| Source ID | Source plugin | Earlier history |
|---|---|---|
wps | WP Swings Wallet System | Yes |
terawallet | TeraWallet (Wallet for WooCommerce) | Yes |
yith | YITH WooCommerce Account Funds | Yes |
wcaf | Account Funds for WooCommerce (WooCommerce Account Funds 4.x) | Yes |
meta_<hash> | Custom meta key, set up in the Migration section of the Tools tab. The ID is meta_ plus the first 10 characters of the MD5 hash of the meta key. | No |
Tip: To see the exact IDs registered on a site (including a custom meta key and sources added by other plugins), run the command with a made-up ID. The error lists them: Error: Unknown migration source "x". Registered: wps, terawallet, yith, wcaf, meta_1a2b3c4d5e.
wp rb-elbal migrate terawallet --deactivate
wp rb-elbal migrate wps --deactivate --yesExample output:
Source: TeraWallet (Wallet for WooCommerce)
Importable: 13 customers holding 1383.5000 in total.
Back up your database before migrating. The migration only adds Elite Balance ledger entries and never changes the source data, but a fresh backup is the only certain way to undo anything.
Deactivated: woo-wallet/woo-wallet.php (data kept).
Imported: 13
Replayed: 0
Zero skipped: 0
Anomalies: 0
Imported total: 1383.5000
Source total: 1383.5000
Earlier history: the old log (68 entries) is being copied in the background, as reference only. To copy it now instead: wp rb-elbal history copy terawallet --restart --yes
Success: Migration complete; totals reconcile.- Each anomaly (a balance that could not be imported safely) prints as a warning with its issue and the stored value, for example
Warning: User #57: not_numeric (value "n/a"). Fixed in 1.1.0: earlier versions printed “Array”. Fix the value in the source plugin’s data and run the command again. - When the totals do not match, the last line is
Warning: Totals differ: review the anomalies before switching over.instead of the success line. - For the four sources with a transaction log, a finished migration starts copying that log into the earlier history archive in the background, and the command prints the “Earlier history” line. To copy it in the same process instead, run the
history copycommand it suggests.
history copy
↑ Back to topNew in 1.1.0. Copies a source plugin’s transaction log into the earlier history archive, in the same process, and prints a report. The archive is reference only: it never touches the ledger or any balance, and the old plugin’s tables are read, never changed. Re-running is safe: entries already archived are skipped, so a second run only adds what is missing. Customers see the archive on the Earlier activity tab of their wallet page; staff see it on the customer’s wallet screen.
| Argument or option | Required | Description |
|---|---|---|
[<source>] | No | A source with a transaction log: wps, terawallet, yith or wcaf (or a third-party source that supports history). Default: wps. |
--restart | No | Clears a stuck “running” status from an interrupted copy before starting. The archive itself is kept. |
--yes | No | Skips the confirmation prompt. |
wp rb-elbal history copy wps --yes
wp rb-elbal history copy terawallet --restartExample output:
Old log entries: 68. Copying into the earlier-history archive (reference only; the ledger is not touched).
Copied (new): 68
Already archived: 0
Skipped, no customer: 0
Skipped, unreadable: 0
Skipped, zero amount: 0
Skipped by a filter: 0
Success: Earlier history copied.- The command stops with an error when the source has no log (its log table is empty or no longer exists), or when a copy is already running; pass
--restartif that run was interrupted. - If the copy fails part way, nothing is marked done. Check the
elite-balancelog under WooCommerce > Status > Logs, fix the cause, and run the command again. - Skipped entries are counted, not lost: “no customer” means the entry could not be matched to a registered customer account, “unreadable” means its amount could not be read, and “by a filter” means custom code excluded it through
rb_elite_balance_history_entry.
history status
↑ Back to topNew in 1.1.0. Prints one row per source that has a transaction log: how many entries the old log holds, how many are archived, the copy status (not copied when no copy has run) and when the last copy finished.
$ wp rb-elbal history status
+------------+---------+----------+------------+---------------------+
| source | old_log | archived | status | finished |
+------------+---------+----------+------------+---------------------+
| wps | 0 | 0 | not copied | |
| terawallet | 68 | 68 | complete | 2026-08-24 09:13:00 |
| yith | 0 | 0 | not copied | |
| wcaf | 0 | 0 | not copied | |
+------------+---------+----------+------------+---------------------+Ledger checks
↑ Back to topreconcile
↑ Back to topThe integrity check. For every wallet, it confirms that the stored balance equals the sum of the wallet’s transactions and the balance after of its latest transaction. Run it after a migration, before switching over from another plugin, or on a schedule as part of your monitoring.
| Option | Required | Description |
|---|---|---|
--batch-size=<n> | No | How many wallets are checked per database query. Default: 500. Lower it on small database servers, raise it to finish faster on large stores. |
$ wp rb-elbal reconcile
Success: All 1204 wallet(s) reconcile: sum(transactions) == balance.
$ wp rb-elbal reconcile --batch-size=2000When a wallet does not reconcile, the command prints a table with wallet_id, user_id, balance, sum_of_txns and last_balance_after, ends with Error: 1 of 1204 wallet(s) FAILED reconciliation. and exits with status 1. A mismatch means something changed the database outside Elite Balance (a direct SQL edit or a partial restore). Keep the output and contact support.
expire-holds
↑ Back to topReleases pending holds whose expiry time has passed, and prints how many it released. Elite Balance never sets an expiry on its own holds (checkout reservations and withdrawal requests); expiry exists for custom code that places holds with an expires_at time. An hourly background task (rb_elbal_expire_holds) already does this and also releases holds left behind by deleted or dead orders, so you only need the command to run it on demand.
| Option | Required | Description |
|---|---|---|
--limit=<n> | No | Maximum holds to release in one run. Default: 100. |
$ wp rb-elbal expire-holds --limit=500
Success: 0 hold(s) expired.Withdrawals
↑ Back to topThe wp rb-elbal withdrawals commands work the same queue as WooCommerce > Elite Balance > Withdrawals. The plugin never sends money: you pay the customer through your bank or PayPal first, then record the transfer. See Withdrawals.
Tip: Add WP-CLI’s global --user=<admin login or ID> option to transfer and reject so the request records which staff member acted. Without it, no staff member is recorded.
withdrawals list
↑ Back to top| Option | Required | Description |
|---|---|---|
--status=<status> | No | Only requests with this status: pending, processing, transferred, rejected or cancelled. |
--limit=<n> | No | Maximum rows. Default 20, maximum 200. |
Columns: id, user (login and ID), amount, method (the payout method key), status, requested (UTC) and reference. Newest first.
wp rb-elbal withdrawals list --status=pending
wp rb-elbal withdrawals list --limit=50withdrawals show
↑ Back to topPrints one request in full: ID, user (login, email and ID), status, amount, fee, net amount, method, payout details, customer note, admin note, transfer reference, hold ID, transaction ID, and created and updated times (UTC).
wp rb-elbal withdrawals show 12Important: The output includes the customer’s payout details (bank account or PayPal email). Treat terminal output and logs that contain it as personal data. Payout details are blanked automatically 30 days after a request is closed, after which show prints them empty.
withdrawals transfer
↑ Back to topMarks a pending or processing request as transferred. The reserved funds become a Withdrawal debit for the full requested amount; the fee and the net amount sent are recorded on the request and in the transaction note. Run it only after the money has actually been sent.
| Argument or option | Required | Description |
|---|---|---|
<id> | Yes | Request ID. |
--reference=<reference> | Yes | The bank or PayPal transaction reference. |
--fee=<fee> | No | Fee deducted from the requested amount. Default 0. Must be zero or more and less than the amount. |
--note=<note> | No | Internal staff note. Not shown to the customer. |
$ wp rb-elbal withdrawals transfer 12 --reference=SEPA-2026-0716 --fee=2.00 --user=admin
Success: Request #12 transferred: 30.0000 debited, 28.0000 sent (fee 2.0000), reference SEPA-2026-0716.The command is idempotent: running it again for the same request never debits twice. The customer receives the Withdrawal transferred email if it is enabled.
withdrawals reject
↑ Back to topRejects a pending or processing request and releases the reserved funds, so the customer can spend them again. Nothing is debited.
| Argument or option | Required | Description |
|---|---|---|
<id> | Yes | Request ID. |
--reason=<reason> | Yes | The rejection reason. It is shown to the customer on their wallet page and in the Withdrawal rejected email, so write it for them. |
$ wp rb-elbal withdrawals reject 12 --reason="The payout details are incomplete or incorrect" --user=admin
Success: Request #12 rejected; the reserved 30.0000 is available to the customer again.There is no command to move a request to Processing or to cancel it: use the Withdrawals tab for Processing, and customers cancel their own pending requests from their wallet page.
Scripting examples
↑ Back to topCredit a list of customers once, safely re-runnable (the key makes a second run a no-op):
while IFS=, read -r user amount; do
wp rb-elbal credit "$user" "$amount" \
--note="Spring promotion 2026" \
--key="promo:spring-2026:$user"
done < credits.csvAlert when the ledger does not reconcile (for example from a nightly cron job):
wp rb-elbal reconcile --quiet || echo "Elite Balance reconcile failed on $(hostname)" | mail -s "Wallet ledger alert" ops@example.comFor larger one-off credits or debits with an audience, a review step and an operation history, the admin Bulk Operations and CSV Import screen is usually the better tool.