WP-CLI

WalletPro registers a full wp wallet command suite for WP-CLI, giving developers and system administrators scriptable access to wallet balances, transactions, ledger verification, and diagnostics without touching the WordPress admin UI.

Overview

The wp wallet command group is available whenever WP-CLI is installed and WalletPro is active. It covers the full surface of wallet operations: reading balances, posting credits and debits, inspecting individual transactions, verifying ledger integrity, and running the built-in health checker (wp wallet doctor). All commands respect WooCommerce HPOS and emit machine-readable output suitable for shell pipelines and CI workflows.

Commands follow the standard WP-CLI conventions: global flags like --url, --path, --quiet, and --format work as expected. Output defaults to a human-readable table; pass --format=json or --format=csv for scripting.

Requirements

Command Reference

wp wallet balance

Reads the current wallet balance for one or more customers.

# Single customer by user ID
wp wallet balance --user=42

# Single customer by email
wp wallet balance --user=jane@example.com

# All customers with a non-zero balance, JSON output
wp wallet balance --all --format=json

# Filter by currency (multi-currency installs)
wp wallet balance --all --currency=EUR --format=csv

Parameters

Example output

# wp wallet balance --user=42
+--------+----------+----------+---------------------+
| ID     | Email                | Balance  | Currency |
+--------+----------+----------+---------------------+
| 42     | jane@example.com     | 75.00    | USD      |
+--------+----------+----------+---------------------+

wp wallet credit

Posts a credit (addition) to a customer's wallet. Creates a ledger entry with an optional reason string. Equivalent to a manual credit in the admin UI but scriptable and auditable via stdin/pipe.

# Credit $25 to user 42 with a reason
wp wallet credit --user=42 --amount=25.00 --reason="Loyalty reward Q2"

# Credit in a specific currency
wp wallet credit --user=42 --amount=10.00 --currency=EUR --reason="EU promo"

# Bulk credit from a CSV file (user_id,amount,reason)
while IFS=, read uid amount reason; do
  wp wallet credit --user="$uid" --amount="$amount" --reason="$reason"
done < credits.csv

Parameters

wp wallet debit

Posts a debit (deduction) to a customer's wallet. The command rejects the operation if it would drive the balance below zero unless --allow-negative is passed.

# Debit $10 from user 42
wp wallet debit --user=42 --amount=10.00 --reason="Correction: duplicate top-up"

# Force negative balance (use with caution)
wp wallet debit --user=42 --amount=100.00 --allow-negative --reason="Chargeback recovery"

Parameters

wp wallet transactions

Lists wallet transactions for a customer or across all customers, with optional date and type filters.

# All transactions for user 42
wp wallet transactions --user=42

# Credits only, date range
wp wallet transactions --user=42 --type=credit --after=2025-01-01 --before=2025-06-30

# Export full ledger to CSV
wp wallet transactions --all --format=csv > ledger-export.csv

# Last 50 transactions across all users, newest first
wp wallet transactions --all --limit=50 --orderby=date --order=desc

Parameters

wp wallet set-balance

Sets a customer's wallet balance to an exact amount. This is a destructive operation that posts a synthetic credit or debit to reconcile the difference. It is intended for data migrations and initial imports, not routine use.

# Set user 42's balance to exactly $50.00
wp wallet set-balance --user=42 --amount=50.00 --reason="Migration from legacy system"

# Dry run: show what would happen without writing
wp wallet set-balance --user=42 --amount=50.00 --dry-run

Parameters

wp wallet expire

Manually triggers expiry processing for credits that have passed their expiry date. Under normal operation this runs on the WalletPro daily cron, but you can invoke it explicitly after a bulk import or during maintenance windows.

# Expire all overdue credits now
wp wallet expire

# Dry run: show which credits would expire
wp wallet expire --dry-run

# Expire credits for a specific user only
wp wallet expire --user=42

wp wallet redemption

Manages redemption codes (gift codes / promotional credit codes).

# Create a single code worth $20
wp wallet redemption create --amount=20.00 --code=WELCOME20

# Generate 100 unique codes worth $5 each, prefix PROMO
wp wallet redemption generate --amount=5.00 --count=100 --prefix=PROMO --format=csv > codes.csv

# Check the status of a code
wp wallet redemption get --code=WELCOME20

# Void (disable) a code
wp wallet redemption void --code=WELCOME20

# List all active codes
wp wallet redemption list --status=active --format=table

Subcommands

wp wallet doctor

wp wallet doctor is the built-in health and integrity checker. It runs a series of diagnostic checks and reports pass/warn/fail status for each. It is the first tool to run when troubleshooting unexpected balances, failed checkouts, or integration issues.

# Run all checks (default)
wp wallet doctor

# Run only ledger integrity checks
wp wallet doctor --check=ledger

# Run only environment checks
wp wallet doctor --check=env

# Output as JSON for CI pipelines
wp wallet doctor --format=json

# Exit with non-zero status on any failure (useful in CI)
wp wallet doctor --strict

Checks performed

Example output

Running WalletPro Doctor...

✔ php_version          PHP 8.2.18, OK
✔ wc_version           WooCommerce 9.1.2, OK
✔ hpos_compat          HPOS enabled and WalletPro flag matches, OK
✔ db_tables            All 4 tables present, schema current, OK
✔ cron_jobs            walletpro_daily_expiry scheduled, OK
⚠ webhook_secret       Secret is set but fewer than 32 characters, WARN
✔ hmac_chain           1,204 ledger rows verified, OK
✔ balance_consistency  All 87 wallets consistent, OK
✔ orphan_transactions  No orphans found, OK
✔ spending_limits, OK
✔ cashback_rules, OK
✔ kyc_gating, OK

Summary: 11 passed, 1 warning, 0 failed.

Bulk Import Pattern

A common use case is migrating wallet balances from a previous system. The recommended pattern uses wp wallet set-balance with --dry-run first, then a second pass without it.

#!/usr/bin/env bash
# import-wallets.sh
# CSV format: email,amount
# Example row: jane@example.com,75.00

CSV="wallets.csv"
DRY_RUN="--dry-run"  # Remove this flag for live run

while IFS=, read email amount; do
  echo "Setting $email → $amount"
  wp wallet set-balance \
    --user="$email" \
    --amount="$amount" \
    --reason="Migrated from legacy wallet system" \
    "$DRY_RUN"
done < "$CSV"

echo "Done. Run wp wallet doctor to verify consistency."

Using WP-CLI in Multisite

On WordPress multisite installations, include --url=<site-url> to target a specific subsite. WalletPro maintains per-site wallet tables, so balances are scoped to the site being addressed.

# Balance for user 42 on a specific subsite
wp wallet balance --user=42 --url=https://store2.example.com

# Doctor check for a specific subsite
wp wallet doctor --url=https://store2.example.com --format=json

Exit Codes

Extending wp wallet

Third-party plugins can register additional subcommands under the wp wallet namespace using the standard WP-CLI WP_CLI::add_command() API. WalletPro fires the walletpro_cli_init action after registering its own commands, which is the correct hook to attach custom subcommands.

// In your plugin or theme functions.php
add_action( 'walletpro_cli_init', function() {
    if ( ! defined( 'WP_CLI' ) || ! WP_CLI ) {
        return;
    }
    WP_CLI::add_command( 'wallet my-subcommand', 'My_Wallet_Subcommand' );
} );

Related Pages

• REST API, HTTP alternative to all wallet operations.
• Hooks & Filters, PHP actions and filters fired during CLI operations.
• Audit Ledger, How the HMAC chain is constructed and verified.
• Redemption Codes, Admin UI equivalent of wp wallet redemption.