Wallet and Subscription Credits

This is the core monetization layer for template buyers. Billing events and AI usage both settle into wallet balances.

What You Get

• Two-bucket wallet model:
  • planBalance: resets by subscription cycle
  • permanentBalance: top-up credits, non-expiring
• Automatic deduction priority: plan first, permanent second
• Full ledger trail in t_wallet_transaction
• User wallet APIs in /v1/wallet/*

Code Map

• Wallet schema: packages/db/src/drizzle/schema/wallet.ts
• User wallet API: apps/ship-api/src/module/wallet.ts
• Wallet services: apps/ship-api/src/services/wallet/index.ts
• User UI: apps/ship/src/app/[locale]/(app)/credits
• Admin UI: apps/ship/src/app/[locale]/(admin)/admin/wallets

Real Flow in Production

1. Stripe checkout succeeds.
2. Webhook writes order/subscription updates.
3. Wallet service grants or refreshes credits.
4. Consumption (for example AI generation) deducts balances.
5. All mutations are queryable in wallet transaction history.

What Buyers Usually Customize

1. Credits granted per plan.
2. Top-up package definitions and price points.
3. Ledger labels/meta shown in UI.
4. Manual adjustment policy for admin operations.

Launch Checklist

1. Subscription renewals grant the expected credits exactly once.
2. Cancellations and refunds do not leave stale balance states.
3. Wallet transaction history in UI matches DB ledger.
4. Admin manual operations are audited.

Next Steps