Credit System & Pricing

Credit logic	lib/credits/creditSystem.ts
React hook	lib/hooks/useCredits.ts
Firestore path	users/{uid}/settings/credits
Initialized at	User registration (AuthProvider.tsx)

---

Screenshot: The credits

Pricing Tiers

Free Plan (default)

Monthly credits	30
Stories per month	~6 (5 credits each)
Quizzes per month	~30 (1 credit each)
Cost to us per user	~$0.86/month (6 stories × $0.14)
Price	$0

Pro Plan

Monthly credits	150
Stories per month	~30 (5 credits each)
Quizzes per month	~150 (1 credit each)
Cost to us per user	~$4.30/month (30 stories × $0.14)
Suggested price	$4.99/month
Margin	~14%
How to upgrade	Contact admin

---

Credit Costs

Action	Credits	Actual API cost
Generate 1 story (6 pages)	5	~$0.14
Take 1 quiz (5 questions)	1	~$0.014

Cost Breakdown Per Story ($0.14)

Component	Cost	%
SafetyGuardian (LLM)	$0.00005	0.04%
StoryWriter (LLM)	$0.00067	0.47%
Illustrator × 6 (image gen)	$0.12013	83.8%
Narrator × 6 (TTS)	$0.02250	15.7%

Cost Breakdown Per Quiz ($0.014)

Component	Cost	%
QuizMaster × 5 (LLM)	$0.002	14%
TTS for questions × 5	$0.012	86%

---

Monthly Cost Projections

Users	Plan	Stories/mo	Quizzes/mo	Monthly cost
100	Free	600	3,000	~$86
100	Pro	3,000	15,000	~$430
1,000	Free	6,000	30,000	~$860
1,000	Mixed (80% free, 20% pro)	12,000	60,000	~$1,720

Revenue from 200 Pro users at $4.99/mo = $998/mo → covers 1,000 mixed users.

---

How Credits Work

Monthly Reset

• Credits reset to monthlyLimit on month change — 30 for Free users, 150 for Pro users
• The monthlyLimit field in Firestore is the source of truth; the reset restores to that value
• Unused credits do NOT roll over
• Reset is automatic — checked on every getUserCredits() call by comparing lastResetMonth with current month

Credit Flow

User clicks "Create My Story"
    │
    ▼
Check: credits >= 5?
    ├── NO → Show "Not enough credits" alert
    │
    └── YES → Deduct 5 credits from Firestore
                │
                ▼
            Start story generation

User clicks "Magic Quiz"
    │
    ▼
Check: credits >= 1?
    ├── NO → Show "Not enough credits" alert
    │
    └── YES → Deduct 1 credit from Firestore
                │
                ▼
            Start quiz generation

---

Firestore Schema

users/{uid}/settings/credits {
  credits: 30,              // Current balance
  lastResetMonth: "2026-04", // For monthly reset detection
  totalCreditsUsed: 15,     // Lifetime usage tracking
  storiesThisMonth: 3,      // Stories created this month
  quizzesThisMonth: 5,      // Quizzes taken this month
  monthlyLimit: 30,         // Plan limit — 30 (Free) or 150 (Pro). Source of truth for isPro.
  proSince: null,           // ISO date when Pro was activated (null for Free users)
  proExpiresAt: null,       // ISO date of Pro expiry — end of current month (null for Free users)
}

---

UI Locations

Location	What's shown
Dashboard (profile card)	💎 credits remaining + upgrade button (Free) or ⭐ Pro badge (Pro)
Profile page	Credits card with plan label, usage breakdown, expiry date (Pro), upgrade button (Free)
Create page	💎 credits below Create button
Story end page	Credit check before quiz

---

Pro Upgrade Flow

Pro upgrades are handled via the admin panel (storybook-for-kids-adm/, local only):

1. User clicks "Upgrade to Pro" button → opens https://www.kidstory.app/upgrade in a new tab
2. Admin opens the local admin panel and toggles the user to Pro
3. Admin panel writes to Firestore:
   • monthlyLimit: 150 — sets the plan limit (source of truth for isPro)
   • credits: currentCredits + 150 — adds 150 to whatever the user has left (e.g. 12 remaining → 162; new user with 30 → 180)
   • proSince: <ISO date> — activation timestamp
   • proExpiresAt: <end of current month ISO date> — expiry date
4. useCredits hook reads monthlyLimit and derives isPro = monthlyLimit > 30
5. Profile page shows "Pro Plan" label + expiry date + "⭐ Pro" badge instead of upgrade button

Future: integrate Stripe/payment gateway for self-serve upgrades.