Wallet movements and customer transactions (ledger alignment)
Overview
customer_transaction rows are the billing / GL-style ledger for the CRM. wallet_ledger remains the operational wallet history. For card wallet top-up and admin cash / manual wallet credit, the API now creates a matching customer_transaction with negative retail_cost (funds received), payment_type set to:
wallet_topup_card: top-up via charged payment method (POST /crm/wallet/topup)wallet_topup_cash: manual credit (POST /crm/wallet/credit, e.g. cash / bank)wallet_adjustment_debit: admin wallet debit (POST /crm/wallet/debit) posts a positive line (adjustment charge)
Each line stores wallet_ledger_id pointing at the corresponding wallet_ledger row for reconciliation.
Sign convention vs GAAP
In this subledger, negative retail_cost means a line that reduces net charges from the customer’s perspective (e.g. wallet top-up / payment-style credits); positive means a charge-like line (e.g. invoice, wallet adjustment debit). That is a CRM billing convention, not a substitute for formal GAAP presentation.
US GAAP does not mandate this particular sign for internal tables. Compliance depends on double-entry in the general ledger, account mapping (cash, AR, unearned revenue, etc.), and financial statement preparation, not on whether customer_transaction.retail_cost uses plus/minus. For operators, prefer UI that shows absolute amount + label and optionally a running balance, rather than relying on raw sign alone. The billing All Transactions table formats retail_cost with a bold amount and a superscript Cr / Dr (credit / debit charge; tooltips spell this out) plus green/red under the column Owed / credit, so type is not conveyed by color alone. Dr here means a charge to the customer (amount owed), not “your card was debited.”
Pay invoice from wallet
Pay Invoice includes Wallet only when the customer has a positive wallet balance; it calls POST /crm/payments/invoice with routing_mode: wallet_only (full amount must be covered). Saved card still uses hybrid routing: wallet is applied first, then the card for any remainder.
Auto-deduct wallet when an invoice is created?
Not implemented by default. Prepaid vs postpaid is a business rule: silently zeroing wallet when an invoice is issued can surprise customers and complicates partial payments, credits, and disputes. Safer pattern: issue the invoice, then explicitly pay (wallet-only, card, hybrid, or staff manual types). If product later needs auto-apply, add a clear setting (e.g. per customer or per invoice) and document GL impact.
Postpaid
Wallet credits reduce customer.outstanding_balance up to the credited amount (for customer_payment_type = postpaid).
Invoicing
Uninvoiced wallet-sync lines are customer prepayments. The Generate Invoice preview on the invoice list excludes lines whose payment_type starts with wallet_ so routine invoices are not accidentally reduced by prepayment credits. To apply a prepayment to a specific invoice, use a workflow that selects explicit transaction_ids (if your tooling supports it), or handle adjustments outside this default preview.
Tax: New invoices from outstanding transactions store customer_invoice.retail_cost = sum(line retail_cost) + sum(line tax_amount) (amount due). List/detail API responses also recompute that total from linked lines so older invoices without tax folded into retail_cost still show and charge the correct amount. PDF subtotal/tax/footer use line items, not the raw invoice header alone.
Permissions
POST /crm/wallet/topup: authenticated users who can use the app (customers use card top-up).POST /crm/wallet/creditandPOST /crm/wallet/debit: requiremanage_customer_wallet(granted toadminandcustomer_service_agent_2in default role seeds). Re-runpopulate_roles_permissions(or equivalent) after deploy so the permission exists and is assigned.
Manual “credit” in Add Transaction
The UI no longer offers manual credit transaction entry, because it did not credit the wallet. Use Billing → Wallet → Cash / manual (staff) or invoice payments instead.