Wallet Design
Purpose
How a creator's or merchant's running balance is represented — the technical counterpart to creator_profiles.wallet_balance_cents in 03. Database.
Model
- The "wallet" is not a separate ledger system — it's a running balance derived from summing unpaid Commissions (see Table Specifications), mirrored by the actual balance sitting in the user's Paddle account
- Paddle is the actual source of truth for available funds; SellVia's
wallet_balance_centsis a convenience read-model for fast dashboard display, kept in sync via webhook events
Creator Wallet
- Accrues per verified Sale (instant, per Money Flow)
- Triggers a bank payout once balance crosses $50
Merchant Billing (was "Merchant Wallet" — retired, see Update below)
- There is no merchant wallet or merchant payout under the current external-tracking model — merchants keep their own revenue directly from their own Shopify checkout
- Instead, SellVia accrues what each merchant owes (commission + platform fee on accepted Sales) into their open Billing Cycle, and bills them for it via Swich each cycle — not threshold-gated, runs on the billing cycle schedule regardless of amount
Open Questions
- Whether creators can view/withdraw below the $50 threshold voluntarily (e.g. closing their account) — reasonable default: allow a manual below-threshold payout only on account closure, not as a standing feature, to avoid undermining the batching efficiency the threshold exists for
Update (2026-08-07): Wallet Now Gated by Billing Cycle Status
"Accrues per verified Sale (instant, per Money Flow)" above is superseded — a creator's wallet balance now only includes commissions whose BillingCycle has reached charged (01. Money Flow, State Machines). Pre-billing commission is "owed" but not yet in the spendable wallet balance — this is the data-layer enforcement of bill-first-then-pay.
Update (2026-08-23): Paddle Removed — SellVia's Own Ledger Is the Source of Truth
"Paddle is the actual source of truth for available funds" (Model section above) no longer applies — Paddle is removed for MVP (Pakistan-only market; see 02. Architecture Decision Log).
Revised model: wallet_balance_cents is not a read-model synced from an external source's account balance — it is the source of truth, computed directly from SellVia's own Commission/BillingCycle/Payout records (sum of Commissions whose BillingCycle is charged, minus anything already paid out). This holds true whether or not a processor is in the loop: Swich (confirmed 2026-08-23, same day as the Paddle removal) is the execution rail that actually moves the money once SellVia's ledger says a payout is due — it does not hold a balance on SellVia's behalf the way a Paddle/Stripe-Connect-style account would. Swich's webhooks tell SellVia "this transfer succeeded/failed"; they don't tell SellVia what's owed — SellVia's own ledger already knows that.
Creator Wallet section above: "per Money Flow" and threshold-gating logic are unchanged; the phrase "mirrored by the actual balance sitting in the user's Paddle account" is removed — replace with "computed from SellVia's own ledger; Swich is notified once a payout is due, it doesn't hold the balance."
Correction to this note (2026-08-23, same date): this update originally claimed the Merchant Wallet section above was "unchanged" — that was wrong. There is no merchant wallet or merchant payout under the current external-tracking model at all; the section has been retired and rewritten as "Merchant Billing" (above), consistent with 05. Payout Process's 2026-08-23 update ("there is no separate merchant payout under the current external-tracking model").
Currency: PKR only. The $50 payout threshold needs re-specifying in PKR — not yet done, flagged as an open item in 01. User Flows' 2026-08-23 update and 05. Payout Process.