Auto-reload

Auto-reload automatically tops up a customer's wallet balance when it falls below a threshold they define, ensuring they always have funds available at checkout without manual intervention.

Overview

Auto-reload lets customers set a minimum balance threshold and a reload amount. When their wallet balance drops to or below the threshold after a purchase or debit, WalletPro queues a background top-up using the customer's saved payment method. The top-up processes like any manual top-up: it runs through the customer's chosen gateway, adds the reload amount to the wallet, and records the transaction in the audit ledger.

From the merchant's perspective, auto-reload drives higher wallet adoption and reduces checkout friction. Customers who enable it rarely abandon a purchase due to insufficient wallet funds.

How it works

The auto-reload cycle follows these steps:

1. A debit occurs on the customer's wallet (purchase, transfer, merchant debit, etc.).
2. WalletPro checks whether the resulting balance is at or below the customer's configured threshold.
3. If the threshold is met and auto-reload is enabled, a top-up job is scheduled via WC_Queue (Action Scheduler).
4. The job charges the reload amount to the customer's saved payment method using an off-session charge request.
5. On success, the reload amount is credited to the wallet and a transaction record is written to the audit ledger with source auto_reload.
6. The customer receives an email notification confirming the reload.
7. On gateway failure, WalletPro retries up to the configured retry limit before sending a failure notification to the customer and, optionally, the store admin.

Merchant setup

Enabling auto-reload globally

Before customers can configure auto-reload, you must enable it at the store level.

1. Go to WooCommerce > WalletPro > Settings > Top-up.
2. Check Enable auto-reload.
3. Configure the options below, then click Save changes.

Auto-reload settings

Viewing auto-reload activity

All auto-reload top-ups appear in the standard transaction ledger. To filter for them:

1. Go to WooCommerce > WalletPro > Transactions.
2. Open the Source filter and select Auto-reload.
3. Apply date range filters as needed.
4. Export via Export CSV to download filtered results.

Failed auto-reload attempts are logged under WooCommerce > WalletPro > Transactions with a status of failed and a note indicating the gateway error.

Customer usage

Finding auto-reload settings

Customers manage auto-reload from their account dashboard:

1. Log in and go to My Account > Wallet.
2. Select the Auto-reload tab.

If the merchant has not enabled auto-reload globally, this tab does not appear.

Enabling auto-reload

1. On the Auto-reload tab, toggle Enable auto-reload on.
2. Set a Reload threshold. This is the balance level that triggers a top-up. For example, entering $10.00 means a top-up fires whenever the balance falls to $10.00 or below.
3. Set a Reload amount. This is how much gets added to the wallet each time a reload fires. For example, $50.00.
4. Select a Payment method from saved methods on the account, or add a new card using the inline form.
5. Click Save auto-reload settings.

After saving, the customer sees a confirmation summary: "Auto-reload is active. Your wallet will be topped up by $50.00 when your balance falls below $10.00, using Visa ending in 4242."

Updating or disabling auto-reload

Customers can return to the Auto-reload tab at any time to change the threshold, reload amount, or payment method. To turn off auto-reload, toggle Enable auto-reload off and save. Any pending queued job for that customer is cancelled.

Reload notifications

Customers receive an email after each reload event:

• Successful reload: Confirms the amount added, the new balance, and the payment method charged.
• Failed reload: States that the charge failed, the reason returned by the gateway (e.g., "Card declined"), and instructs the customer to update their payment method or top up manually.

Email templates are editable under WooCommerce > Settings > Emails: look for WalletPro: Auto-reload successful and WalletPro: Auto-reload failed.

Interaction with other features

Developer reference

Hooks

Use these hooks to extend or monitor auto-reload behavior.

Filters

// Modify the reload amount before the charge is attempted
add_filter( 'walletpro_auto_reload_amount', function( $amount, $customer_id, $wallet_currency ) {
    // Round up to the nearest $5
    return ceil( $amount / 5 ) * 5;
}, 10, 3 );

// Modify the threshold before it is evaluated
add_filter( 'walletpro_auto_reload_threshold', function( $threshold, $customer_id ) {
    return $threshold;
}, 10, 2 );

// Prevent auto-reload for specific customers or conditions
add_filter( 'walletpro_auto_reload_enabled_for_customer', function( $enabled, $customer_id ) {
    if ( some_custom_check( $customer_id ) ) {
        return false;
    }
    return $enabled;
}, 10, 2 );

Actions

// Fires after a successful auto-reload
add_action( 'walletpro_auto_reload_success', function( $customer_id, $amount, $transaction_id, $currency ) {
    // e.g., log to a custom table or trigger a third-party event
}, 10, 4 );

// Fires after all retries are exhausted and the reload has failed
add_action( 'walletpro_auto_reload_failed', function( $customer_id, $amount, $gateway_error ) {
    // e.g., tag the customer in a CRM
}, 10, 3 );

REST API

Auto-reload settings are readable and writable via the WalletPro REST API.

GET /walletpro/v1/customers/{customer_id}/auto-reload

Returns the customer's current auto-reload configuration.

# Example request
curl -X GET https://example.com/wp-json/walletpro/v1/customers/42/auto-reload \
  -H "Authorization: Bearer <token>"

{
  "enabled": true,
  "threshold": "10.00",
  "amount": "50.00",
  "currency": "USD",
  "payment_token_id": 7,
  "last_reload_at": "2026-06-15T14:32:00Z",
  "last_reload_status": "success"
}

PUT /walletpro/v1/customers/{customer_id}/auto-reload

Updates the customer's auto-reload settings. All body fields are optional; only supplied fields are updated.

# Example request
curl -X PUT https://example.com/wp-json/walletpro/v1/customers/42/auto-reload \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "threshold": "15.00", "amount": "75.00", "payment_token_id": 7}'

{
  "enabled": true,
  "threshold": "15.00",
  "amount": "75.00",
  "currency": "USD",
  "payment_token_id": 7,
  "last_reload_at": "2026-06-15T14:32:00Z",
  "last_reload_status": "success"
}

WP-CLI

Inspect and manage auto-reload settings from the command line.

# View a customer's auto-reload config
wp wallet auto-reload get --customer=42

# Enable auto-reload for a customer with specific settings
wp wallet auto-reload set --customer=42 --enabled=1 --threshold=10.00 --amount=50.00 --token=7

# Disable auto-reload for a customer
wp wallet auto-reload set --customer=42 --enabled=0

# List all customers with auto-reload enabled
wp wallet auto-reload list --status=enabled --format=table

# Manually trigger the auto-reload check for a customer (useful for testing)
wp wallet auto-reload trigger --customer=42

# Show pending auto-reload jobs in the Action Scheduler queue
wp action-scheduler list --hook=walletpro_process_auto_reload --status=pending

Troubleshooting