Admin Wallet Freeze
An admin or shop manager can suspend any customer's wallet from the WordPress user profile. A frozen wallet cannot be used at checkout. The freeze can have an optional expiry date, after which it is automatically lifted the next time the customer visits the checkout. Every freeze and unfreeze action is recorded in the wallet audit log.
Freezing a wallet
Go to Users > All Users > [customer] > Edit. A Wallet Freeze panel appears below the Wallet Notes section. The panel shows the current freeze status and provides a form to apply a new freeze.
Fill in:
- Reason (required): a brief note explaining why the wallet is being frozen. Shown in the audit log.
- Expiry date and time (optional): leave blank for an indefinite freeze. If a date is entered, the freeze is lifted automatically once that date-time passes (on the customer's next checkout attempt).
Click Freeze wallet. The panel updates to show the freeze is active, who applied it, when, and the expiry if set.
Unfreezing a wallet
While a wallet is frozen, the panel shows an Unfreeze button. Click it to lift the freeze immediately. The audit log records who unfroze it and when.
Customers cannot lift an admin freeze themselves. This is intentional: the admin freeze is designed for CS suspension, fraud holds, and compliance situations. It is separate from the customer's own self-freeze (Spending Controls), which uses different storage and different semantics.
Auto-thaw on expiry
WalletPro does not run a scheduled job to unfreeze wallets. Instead, expiry is checked lazily: when a frozen customer reaches the WooCommerce checkout, PaymentGateway::is_available() reads the _walletpro_admin_freeze usermeta and compares the stored expiry timestamp against the current time. If the expiry has passed, the usermeta is deleted on the spot and the freeze is treated as not active. The audit log records the auto-thaw event.
This means a wallet whose expiry has passed is still technically frozen in the database until the customer next visits checkout. The freeze will not block non-checkout pages. If you need to confirm whether a freeze has expired, check the expiry date on the profile panel.
Frozen badge on Customer Balances
The Customer Balances page (WooCommerce > Customer Balances) shows a red Frozen badge next to any customer whose wallet has an active admin freeze. The badge only appears for admin-imposed freezes; customer self-freezes are not shown here.
How it interacts with checkout
The freeze check runs inside PaymentGateway::is_available(). This means:
- The wallet payment gateway is hidden from frozen customers on the checkout page.
- The check runs after the existing customer self-freeze check.
- If both an admin freeze and a customer self-freeze are active, both are reported, but only one gateway-unavailable result is needed.
Audit log entries
| Action | When it is written |
|---|---|
wallet_frozen | When a freeze is applied from the user profile panel. |
wallet_unfrozen | When a freeze is manually lifted, or when auto-thaw fires at checkout. |
Storage
The freeze state is stored in WordPress usermeta under the key _walletpro_admin_freeze as a JSON object containing reason, frozen_at (UTC timestamp), frozen_by (user ID of the admin), and expires_at (UTC timestamp or null for indefinite). No separate database table is required.
Hook reference
| Hook | Type | Purpose |
|---|---|---|
| walletpro_wallet_frozen | Action | Fires after a wallet is frozen. Passes ($user_id, $reason, $expires_at, $frozen_by). |
| walletpro_wallet_unfrozen | Action | Fires after a wallet is unfrozen (manual or auto-thaw). Passes ($user_id, $unfrozen_by). |