Skip to main content

Store Credit & Wallet

Overview​

Store Credit holds a per-customer balance the store issued: goodwill, compensation, a promotion, or the value of a return. Beside it sits an append-only transaction ledger. Credit is added or deducted through one service that writes the transaction and the resulting balance together, so every movement carries the balance it produced.

It is a premium module. Enable it from Empora → Modules once your license includes store_credit; enabling it creates its two tables, writes the default settings and schedules the expiry job.

Availability​

ItemValue
Module keystore_credit
TierPremium
Entitlement keystore_credit
Admin tabstore-credit, under Pricing & Promotions
Enabled optionaiowc_module_enabled_store_credit (off until enabled)
REST namespaceaiowc/v1

Store Credit and Wallet are two ledgers​

Both modules ship, and a store can run either or both.

  • Wallet holds money the customer paid in — a top-up they made themselves.
  • Store Credit holds value the store issued. The shopper never paid for it.

They keep their own tables and their own ledgers, because they are not the same money and an accountant needs to tell them apart. What they share is the moment of spending: checkout shows the customer one combined balance, and the order needs one decision about where the money came from.

Issued credit is spent first

When a customer pays with their balance, Store Credit is drawn down before Wallet. Issued credit is the store's own liability and often carries an expiry; wallet money is the customer's and does not. Spending the customer's own money while issued credit sits expiring would be the wrong way round.

Partial application is a normal outcome, not a failure: a customer with 5.00 of credit against a 30.00 order pays the remaining 25.00 by the usual method. Neither ledger can go below zero — each debit is capped at that ledger's own balance.

Because either module may be switched off, every balance read is guarded twice: the module must be present and enabled. A missing ledger contributes zero rather than failing. See Wallet for the other half.

What the module does​

StoreCreditService implements: read a wallet, read a balance, add credit, deduct credit, apply credit to an order, refund credit against an order, an administrator adjustment recorded with the acting admin's id, expiry processing, transaction history, and a checkout calculation that works out how much of an order total the customer's credit may cover.

The one store-credit ledger​

Store Credit owns store credit for the whole plugin. Smart Coupons Advanced and Gift Cards & Store Credit used to keep their own store-credit balances; they now read and write this ledger through StoreCreditLedger:

OperationDoes
credit(user, amount, key, …)Adds value. A retry under the same key writes nothing.
debit(user, amount, key, …)Spends value. Same rule.
balance(user)What the customer holds now.

The idempotency key comes from the event that caused the write (for example smart_coupons:redeem:order:123). It is checked before the write and enforced by a unique index, so a hook that fires twice, a retried job or a migration run twice records the money once.

The ledger is ready once this module has been switched on at the current version and its tables carry the key column. From then on the other two modules use it even if Store Credit is later switched off, so balances already moved here are never spent twice. Their old balances move in once — a customer's when their balance is first read, the rest in bounded batches on admin page loads. The old rows are zeroed with a recorded debit, never deleted; a gift card in a currency other than the store's is not moved and stays a spendable card.

If Store Credit was never switched on

Smart Coupons Advanced and Gift Cards keep their own records. The balances stay spendable but are not combined, and each module shows an admin notice on the Empora screen and the dashboard saying so. Switching Store Credit on moves them into this ledger.

Settings​

Stored in the bundled option row aiowc_storecredit_settings and written when the module is enabled: a checkout switch, a minimum amount to apply, a maximum percentage of an order that credit may cover, account and header display switches, an expiry window in days, partial payment, a balance email, and whether a negative balance is allowed.

REST API endpoints​

Registered by StoreCreditRest::register_routes() on rest_api_init. The customer routes read the signed-in customer's own balance; the rest require an administrator.

MethodPathPurpose
GET/store-credit/walletThe signed-in customer's balance.
GET/store-credit/transactionsThe signed-in customer's ledger.
GET/store-credit/checkout-infoHow much credit may be applied to a given order total.
POST/store-credit/applyApply credit to an order.
GET/store-credit/overviewTotals for an administrator overview.
GET/store-credit/usersCustomers with a balance.
GET/store-credit/users/{user_id}One customer's wallet, read by an administrator.
POST/store-credit/adjustAdjust one customer's balance.
POST/store-credit/bulk-adjustAdjust several customers at once.
GET/store-credit/recent-transactionsThe most recent ledger entries across customers.
GET/store-credit/settingsRead the settings.
PUT / PATCH / POST/store-credit/settingsUpdate the settings.

Database schema​

Created by Schema/DatabaseSchema.php when the module is enabled.

TableHolds
{prefix}aiowc_store_creditOne row per customer: balance, lifetime credit and debit, currency, active flag.
{prefix}aiowc_credit_transactionsEvery movement: amount, type, reference, resulting balance, description, admin id, expiry, idempotency key (unique).

WooCommerce integration​

CreditDisplayHandler adds a balance banner to the cart and checkout, a Store Credit page in My Account, a credit option in the checkout order review, the balance in order emails, and the credit used on the order details page. Each group is behind its own display setting.

HookAdds
woocommerce_before_cartBalance banner on the cart
woocommerce_before_checkout_formBalance banner on checkout
woocommerce_account_menu_itemsStore Credit entry in My Account
woocommerce_account_store-credit_endpointThe My Account credit page
woocommerce_review_order_before_paymentThe credit option in the order review
woocommerce_email_order_metaCredit used, in order emails
woocommerce_order_details_after_order_tableCredit used, on the order details page

Paying from store credit at checkout​

Store credit can pay part or all of an order on the classic checkout and on the Checkout block, together with the Wallet when both are enabled (store credit is used first). The checkout steps, the re-quote when a balance changes, and returning an overpayment are described under Wallet → Spending at checkout.

The Store Credit admin page keeps its "Some orders need a look" notice, now as a list with a count per row and a Show these orders link: returns still owed, open overpayments, and orders from earlier versions, which are left as they are.

Background jobs​

CreditExpiryJob (aiowc_store_credit_expiry) expires credit on a schedule, and is unscheduled when the module is disabled.

Entitlement limits​

The entitlement is a single on/off grant: without store_credit the module stays locked, and while it is absent none of the above loads. No per-customer or per-balance quota is applied by the license.