Monetization — Companion Paywall & Token Allocation

Status: Proposed 2026-07-09 — ready to build · researched against July-2026 store rules and live COGS

The model in one paragraph: free users get a sample — Kaori visible and usable with a small daily voice allowance, other companions shown locked. Paid tiers unlock the full roster plus a monthly voice-token allotment (1 token = 1 spoken reply). Cosmetics (boards, outfits, environments) unlock through BOTH usage (XP/streaks) and payment tiers. Web sells via our existing Stripe; mobile sells via RevenueCat IAP; the backend Mongo user doc is the single source of truth.

Why tokens — the unit economics

Voice is where the money burns. Per Kaori reply (~250–350 chars TTS, ~5k-token prompt):

Cost driver	Per voice reply	Per text reply
OpenRouter LLM (Gemini Flash class)	~$0.008–0.012	~$0.01
ElevenLabs TTS (current model)	~$0.05–0.10	—
ElevenLabs TTS (Flash-class model)	~$0.03–0.05	—
All-in	~$0.04–0.11	~$0.01

Two COGS levers to pull before revenue work (halves cost, better latency):

1. Switch stage TTS to a Flash-class ElevenLabs model (0.5 credits/char vs 1)
2. Enable OpenRouter prompt caching for Kaori's big static persona block (60–80% cheaper repeated context)

The token model (v1)

• 1 token = 1 voice reply (one TTS synthesis of one bot message). Text is NOT tokenized — it gets a coarse anti-abuse daily cap (~50/day free). Simple mental model: voice costs tokens.
• Metering lives server-side: one requireVoiceTokens middleware at the places a /speak fires (routes/botChat.js, routes/dm.js, kaori-live path). Atomic decrement (findOneAndUpdate with $gte: 1 guard) before calling kith. On empty wallet: still return the text reply with voiceExhausted: true so the stage shows a top-up prompt instead of going silent.
• Every debit logs to usage_events (userId, botId, chars, ts) — this doubles as the usage-analytics foundation the UX audit needs.
• Free daily grant is lazy (a dailyGrant date field checked on first request of the day) — no cron.
• The Kith sidecar stays dumb; Express is the only gate.

Tiers (starting point — tune with usage_events data)

Tier	Companions	Voice tokens	Text	Price
Free	Kaori only (sample)	5/day	50 msgs/day	$0
Plus	Full roster	200/mo (rollover ≤2×)	Unlimited*	~$10/mo (existing TrickBook Plus)
Top-up packs	—	e.g. 100 tokens	—	~$4.99 (consumable IAP / Stripe)

Sanity check: 200 voice tokens ≈ $5–7 COGS on Flash+caching (~40% margin before store fees). Free tier worst case ≈ $6/mo per maxed-out user — acceptable sampling cost.

Platform rules (verified July 2026)

• Apple: in-app digital purchases still require IAP (guideline 3.1.1). Post-Epic US anti-steering: apps MAY link out to web checkout, currently 0% Apple commission — but the fee question is back in district court, don't build anything that assumes 0% is permanent. Web-bought tokens are legal to consume in-app (multiplatform rule).
• Google (US): alternative billing + external links allowed since Dec 2025; Epic settlement (reduced fees) pending approval.
• Practical: sell tiers + token packs via IAP in-app on both stores, AND surface a "buy on thetrickbook.com" link on US storefronts to the Stripe checkout. Identical pricing; keep the margin difference.

Architecture

• RevenueCat for mobile IAP (react-native-purchases — Expo-compatible, needs the dev-client build we already need for the stage; free until ~$2.5k MTR). One webhook → backend.
• Keep the existing Stripe flow (routes/payments.js already implements the full TrickBook Plus lifecycle) — extend with tier price IDs + one-time token-pack prices. Don't migrate it into RevenueCat in v1.
• Mongo is canonical: user.subscription (existing) + user.wallet.voiceTokens (new) + unlocks collection (new). Both webhooks (Stripe, RevenueCat) write into the same fields, idempotent on event id. The app gates from GET /api/payments/subscription, never from client-side store state.

Unlockables

One unlocks collection: {userId, itemId, source: 'xp' | 'tier' | 'purchase', grantedAt}. Client only ever asks "is itemId unlocked", never "how". Tier-sourced unlocks deactivate on downgrade; XP- and purchase-sourced are permanent.

Build order by asset cost:

1. Boards (easiest, most on-brand) — separate .glb props, no VRM surgery; deck graphics are cheap content
2. Colorways — runtime MToon base-color texture swaps on the existing VRM; dozens of recolors from one avatar
3. Full outfits (heaviest) — one complete .vrm per outfit (runtime mesh-swapping inside a VRM is fragile); device-cached, lazy-downloaded, keep to 3–5 per companion
4. Environments — independent of the VRM: skybox/ground/props swap in the scene. Kaori gets snow; each sport gets its own vibe. Unlockable the same way.

Apple compliance note: XP/streak-earned cosmetics are fine; directly-purchased cosmetics on iOS must be IAP products — pricing cosmetics in voice tokens is the elegant move (tokens are already a compliant consumable).

Build phases

1. Metering foundation + cost control (backend only): wallet + usage_events + requireVoiceTokens + lazy daily grant + voiceExhausted; flip TTS to Flash-class; enable prompt caching
2. Free-sample gating: companion list returns locked/unlocked per plan; mobile picker + web locked states; text daily cap; adminOverride for QA
3. Web purchases first (fastest to revenue, zero store review): extend payments.js with tier + token-pack prices; paywall + wallet UI on the site
4. Mobile IAP via RevenueCat: store products, RC webhook → same Mongo fields, server-driven paywall screen (bundle into the Kaori-stage EAS build)
5. US steering escape hatch: external purchase links on iOS/Play US storefronts (re-check the Apple fee ruling first)
6. Unlockables v1: unlocks collection, board props + colorway swaps, cosmetics priced in tokens, XP earn rules from usage_events
7. Unlockables v2 + world-building: full outfit VRMs, snowy Kaori environment, per-sport stages
8. Tune with data: usage dashboards, re-price allotments from observed chars/reply + cache hit rates; every new companion (Tony, etc.) is then content, not new billing plumbing