Core Wallet

The base of the plugin. Every other feature — cashback, refund, withdrawal, transfer — moves money in and out of this layer.

Setting up?

Skip to General Settings for the step-by-step admin tab walkthrough (currency, low-balance threshold, daily login reward).

What It Does

ForMeans
CustomerA wallet balance attached to their account. Top up, spend at checkout, see every move on a clear activity feed
AdminOne source of truth for store credit, with a full audit trail and one-click manual adjust

How Customers See It

Three places the balance shows up:

SurfaceWhere
My Account → My WalletFull dashboard with hero card, top-up, send, withdraw
Wallet CentralStandalone full-screen experience at /wallet-central/
Header / footer / pageDrop the [wkwp_wallet_balance] shortcode anywhere

Every credit / debit also shows up in the customer's activity feed — type icon, amount, date, related order link.

The customer-facing balance hero, on My Wallet:

Credit-card hero on the My Wallet page — brand strip, balance, masked wallet ID, currency chip

The full activity card on the same page:

Recent activity card — title, view-all, filter chips, transaction rows

How Admin Adjusts a Balance

Two entry points:

A. From the user list (fastest)

  1. Users → All Users → click the customer
  2. Scroll to the Wallet card
  3. Type an amount + a note in the Credit or Debit field
  4. Click Update Wallet

B. From any order

  1. Open the order edit screen
  2. Side meta-box Wallet → Manual adjust button

Both write a row to the audit trail tagged as a manual admin action.

Low-Balance Alert

When a customer's balance drops below the threshold you set, they get an automatic email.

SettingDefaultNotes
EnableONtoggle off if you don't want alerts
Threshold100currency value

One alert per drop

Customers don't get spammed. The alert fires only when balance crosses the threshold downward — debits that happen below the threshold don't re-fire it.

Multi-Currency

If you run WOOCS or YITH Multi Currency, each customer gets a balance per active currency. Switching currency in the front-end shows the matching balance.

Skip this in Wallet → Settings → General → Multi-currency mode if you want a single base-currency balance.

Settings

Wallet → Settings → General

SettingDefaultWhat it does
Default currencymatches WCbase currency for new wallets
Show balance to customerONhides the My Wallet UI when off
Allow negative balanceOFFonly relevant if BNPL is enabled
Low-balance threshold100fires alert below this
Wallet display nameWalletbrand name (e.g. "Store Credit", "Coins")
Multi-currency modeautoonly meaningful with WOOCS / YITH active

Common Scenarios

Refund a customer to wallet (one-off)

Open the order → Refund → tick "Refund to wallet". Wallet credited the refund amount + email sent. See Refund to Wallet.

Give 100 customers a ₹50 bonus (bulk)

CSV upload via Wallet → Bulk Credit / Debit. Goes async — customer emails fire as each row processes. See Bulk Credit / Debit.

Customer claims their balance is wrong

  1. Open their user profile → Wallet card
  2. Look at Recent transactions in the same card — last 10 ledger rows
  3. Adjust manually if needed → audit row gets your admin name in the reference

When Something Goes Wrong

ProblemFix
Customer's balance doesn't reflect a recent changeStale cache — Wallet → Status → Tools → Wallet → Clear cache
Manual adjust button missingCurrent admin role lacks manage_woocommerce capability
Customer says balance "disappeared"Likely a withdrawal request — debit happens at request time, not approval time. Reject the request to refund
For developers — read & write the wallet programmatically

Storage

WhereKeyType
User meta_wkwc_wallet_amountdecimal as string
User meta_wkwc_wallet_amount_<currency>per-currency balance (multi-currency mode)

Only mutate through the public API — direct meta writes bypass the ledger and break analytics.

API

// Credit 250 to user with audit ref
WKWP_Wallet_Core::credit( $user_id, 250.00, [
    'order_id'  => $order->get_id(),
    'reference' => 'cashback:rule#12',
    'note'      => 'Cashback on order #' . $order->get_id(),
] );

// Debit 99.50
WKWP_Wallet_Core::debit( $user_id, 99.50, [
    'order_id'  => $order->get_id(),
    'reference' => 'gateway:wkwc_wallet',
    'note'      => 'Order #' . $order->get_id() . ' wallet payment',
] );

Both methods:

  1. Validate amount > 0 (throws on negative or zero)
  2. Re-fetch live balance under DB lock
  3. Update user meta
  4. INSERT one ledger row + denorm history row
  5. Bust cache
  6. Fire wkwp_wallet_balance_changed (+ legacy wkwc_wallet_amount_updated)
  7. Trigger low-balance email if threshold crossed

Selected hooks

HookTypeWhen
wkwp_wallet_balance_changedactionafter every credit / debit, args ($user_id, $amount, $type, $balance_after)
wkwc_wallet_amount_updatedactionlegacy alias
wkwp_wallet_low_balance_alertactioncrosses threshold downward
wkwp_wallet_credit_amountfiltermutate amount before credit
wkwp_wallet_debit_amountfiltermutate amount before debit
wkwp_wallet_history_labelfilterrename ledger types in history view

Full list: Filters & Hooks.

REST

EndpointAuth
GET /wkwp-wallet/v1/walletsadmin
GET /wkwp-wallet/v1/wallets/{user_id}admin
GET /wkwp-wallet/v1/transactions?user_id=&type=&from=&to=admin

See REST API.

Concurrency

DB row lock under SELECT ... FOR UPDATE. Tested under 100 concurrent ops per user without double-credit / double-debit.