Migrating from another wallet plugin

Before you start

Back up your database. The migration only adds Elite Balance ledger entries and never changes or deletes the old plugin’s data, but a fresh backup is the only certain way to undo anything. The migration screen repeats this in bold, because we mean it.

What gets migrated

Customer balances. Each customer with a positive balance in the old plugin receives one opening credit in the Elite Balance ledger, labeled as a migrated balance. The old plugin’s own transaction history stays untouched in your database for reference; it is not imported, because its records are not reliable enough to build an auditable ledger from.

Zero balances are skipped (no empty wallets are created). Broken values (non-numeric, negative) are never imported silently: they are listed per customer in the report so you can fix them at the source and run again. The same goes for ambiguous data: a customer with more than one stored value for the same balance key is flagged in the report rather than guessed at.

Running it

1. Open WooCommerce → Elite Balance → Tools. The Migration section shows what matters on this site: a plugin whose data was detected gets a full card with a green “Data detected” badge (blocked, running, and completed states carry their own badges), while supported plugins with nothing to import stay collapsed on one line, expandable if you know better than the detection. If nothing is found anywhere, one compact card says so and lists everything that was checked. The Overview also shows a prompt card while importable data is waiting.
2. While the old wallet plugin is active, the screen shows a required checkbox: Deactivate it first. This is the freeze: an active wallet plugin could change balances mid-import, and two wallet systems must never share a checkout. Ticking it deactivates the plugin the same way the Plugins screen does. Its data is kept; nothing is uninstalled or deleted.
3. Click Migrate balances now and type MIGRATE to confirm.
4. Read the report: imported count, skipped zeros, the imported total against the source total, and the reconciliation verdict in green or red. Anomalies show as a short preview with links to each customer and the offending source value, plus a Prepare the full list (CSV) button: the complete list is re-detected from the source in the background (large stores take a little while; the report shows progress), and the download button appears when the file is ready. Each row carries the raw value alongside the issue, so whoever fixes the data sees exactly what is stored; values you fix at the source drop out of the next preparation. Clearing a report removes only the report itself; imported balances, the ledger, and the old plugin’s data are untouched, and a re-run still never imports a balance twice.

The whole run is re-runnable, and that is a feature, not a risk: every balance imports at most once no matter how many times you run it, enforced by the ledger itself, and a re-run counts replays instead of importing again. Running again is how you finish an interrupted run, pick up customers who joined the old system after the first pass (the classic two-step cutover: big run early, small delta run at the final switch), and import the customers whose broken values you fixed from the anomaly list. Large stores run in background chunks; refresh to follow progress.

Once complete, the report and its stats stay put on the Tools tab, and the Overview carries a summary card linking back to it.

Supported plugins

WP Swings Wallet System (the free and pro plugins), TeraWallet (Wallet for WooCommerce), YITH WooCommerce Account Funds, and Account Funds for WooCommerce (the official extension, by Kestrel) support ships built in. TeraWallet balances are derived from its own transaction history, the source of truth its cached balance sometimes disagrees with, and customers holding entries in a currency other than your store currency are reported per customer rather than silently converted. YITH balances import from the fund meta the plugin itself spends from (its log table is display history and stays untouched); negative balances, which YITH can produce, are reported per customer rather than imported. Account Funds is handled in both of its storage eras: modern versions from its store credit balances table (store-currency rows of registered customers; balances held by guest emails have no account to attach to and stay in its table untouched), legacy versions from its old user meta. If Account Funds has not finished its own internal migration between those eras, the import refuses to run until it has, so no customer’s money is half in each place. Other wallet plugins can be plugged into the same engine through a developer hook: see Custom migration sources, or contact us about your plugin.

Any other plugin: the custom meta key

Most wallet plugins keep each customer’s balance as one numeric user meta. If yours is not listed above, open the Advanced: import from a custom meta key section on the Tools tab (it is collapsed by default, because with four plugins supported out of the box most stores never need it), acknowledge that it is an advanced tool, enter the old plugin’s meta key, and save: a standard migration card appears with what was detected, and the run behaves exactly like any built-in source, report and at-most-once guarantees included.

Two things to know:

• Deactivate the old wallet plugin yourself first. With a custom key, Elite Balance cannot detect which plugin owns the data, so the freeze step is yours.
• Each key is its own source: changing the key clears the previous key’s report (never the ledger), and re-running the same key replays instead of importing twice.

Not sure what the meta key is? Ask us through the contact page with the old plugin’s name, or ask its developer. It is usually documented, and one look at the usermeta table settles it.

Command line

The same migration runs headlessly for staging rehearsals and scripted cutovers:

wp rb-elbal migrate wps --deactivate --yes

See WP-CLI for the full command reference.

Rehearse on staging first: restore a copy of production, run the migration, read the report, spot-check a few customers. On cutover day the real run holds no surprises.