Skip to main content

Referral System

Feature Snapshot​

FieldValue
Feature nameMito Referral Program
Primary goalOrganic user growth through friend invitations and shared content with credit rewards
AvailabilityWorkspace Owners and Editors only
LocationWorkspace sidebar → "Referral" item, accessed at /referral + Asset sharing dialogs

Key Facts the Model Must Know​

  • Two-tier credit system: Invitee gets 1500 credits on signup, inviter gets 3000 when invitee subscribes
  • Owner/Editor access only in each workspace
  • Unique referral codes generated per workspace (10 chars alphanumeric)
  • Feature flag protected: Behind referral-system flag
  • Social sharing built-in: WhatsApp, Twitter, LinkedIn, Email
  • Automatic credit application: Credits used before subscription benefits
  • Asset sharing integration: Referral codes automatically included in public asset shares

Referral Mechanics​

Credit Distribution​

EventRecipientCreditsTiming
Friend signs up with ?ref=CODENew user (invitee)1500Immediately on registration
Invitee subscribes to paid planOriginal user (inviter)3000When subscription activates

Access Requirements​

  • Workspace role: Owner OR Editor (not Viewer)
  • Feature availability: Must have referral-system flag enabled
  • Navigation: Sidebar item shows "Earn 3000" badge
  • Structure: https://app.mito.ai/?ref=WORKSPACE_CODE
  • Code format: 10 characters (0-9, A-Z, a-z)
  • Display format: app.mito.ai/?ref=CODE (shortened for UI)

Asset Sharing Integration​

  • Share URLs: https://share.mito.ai/{token}?ref=WORKSPACE_CODE
  • Toggle control: "Include my referral code" in sharing dialog
  • Default state: Enabled (stored in IndexedDB)
  • Persistence: User preference remembered across sessions

Tracking and Analytics​

  • PostHog events: referral_shared with method (copy, whatsapp, twitter, linkedin, email)
  • Share link events: share_link_copied with has_referral boolean
  • Registration tracking: hasReferral boolean in user_registered event
  • Credit display: Total earned credits shown on referral page

Supported User Flows​

Direct referral sharing​

  1. User accesses /referral from sidebar
  2. Copies referral link via copy button or social share
  3. Analytics event referral_shared fires with method
  4. Friend receives link through chosen channel

Asset sharing with referral​

  1. User selects asset to share in Canvas/Storyboard/Director
  2. Clicks share button (globe icon)
  3. Share dialog shows "Include my referral code" toggle (default: enabled)
  4. User copies share link with optional referral code
  5. Analytics event share_link_copied fires with has_referral status

Friend signup via shared asset​

  1. Friend discovers shared asset at share.mito.ai/{token}?ref=CODE
  2. Views asset and creation process on sharing page
  3. Clicks "Try MITO for free" call-to-action
  4. Redirected to app.mito.ai/login?ref=CODE
  5. Referral code captured and processed during registration

Credit earning​

  1. Referred user subscribes to any paid plan
  2. Original referrer automatically receives 3000 credits
  3. Credits appear in workspace billing balance
  4. No notification sent (credits appear silently)

Example Conversations​

Asset sharing with referrals​

User: How do I share my work and earn credits?
Assistant: When sharing an asset, keep the "Include my referral code" toggle enabled in the share dialog. Your shared work will include your referral code, so when people discover your creations and sign up for Mito, you'll earn credits. They get 1500 credits immediately, and you get 3000 when they subscribe.

Managing sharing preferences​

User: Can I turn off the referral code in my shared assets?
Assistant: Yes! In the share dialog, you can toggle off "Include my referral code" if you prefer to share without referral tracking. Your preference is remembered for future shares. However, keeping it enabled lets you earn credits passively from your shared work.

Accessing referrals​

User: How do I invite friends to Mito?
Assistant: Go to your workspace sidebar and click "Referral" (look for the gift icon with "Earn 3000"). You'll get a unique link to share. When friends sign up using your link, they get 1500 free credits. You earn 3000 credits when they subscribe to a paid plan. You can also earn credits by sharing your assets publicly with your referral code included.

Understanding credit timing​

User: My friend signed up with my link but I didn't get credits yet.
Assistant: You'll earn your 3000 credits only after your friend subscribes to a paid Mito plan. They got their 1500 credits immediately when signing up, but your reward comes when they upgrade from the free plan. This applies to both direct referral links and people who sign up through your shared assets.

Troubleshooting asset sharing​

User: I don't see the referral toggle when sharing my asset.
Assistant: The referral code toggle only appears if: 1) Your workspace has a referral code (check the Referral section in your sidebar), 2) You're an Owner or Editor (not Viewer), and 3) You're sharing the asset publicly. Make sure you meet these requirements.

Common Issues​

ProblemCauseSolution
Referral not in sidebarUser is Viewer role or feature flag offCheck workspace permissions, verify feature availability
No referral toggle in share dialogMissing referral code, insufficient permissions, or private shareVerify workspace has referral code and user is Owner/Editor
Friend got credits but I didn'tInvitee hasn't subscribed yetExplain credit timing - only after paid subscription
Shared asset link doesn't include referralToggle was disabled or browser storage issueCheck toggle state, clear IndexedDB if needed
Link doesn't seem to workCode not captured or cookies clearedEnsure friend clicks link before registering, test in private browser

Technical Integration Points​

Frontend Components​

  • Page: /referral route with referral management UI
  • Sidebar: SidebarReferralItem with "Earn 3000" badge
  • Asset sharing: ShareAssetOrTakeButton with referral toggle
  • Capture: ReferralCapture component saves ?ref= to localStorage
  • Storage: sharePreferencesStorage.ts for referral toggle state

API Integration​

  • Header: X-Referral sent with authenticated requests
  • Response: Workspace referral code in /workspaces endpoint
  • Share URLs: ShareInfo.buildShareUrl() with optional referral parameter
  • Credit system: Automatic credit grants on signup/subscription events

Social Sharing URLs​

  • WhatsApp: https://wa.me/?text=MESSAGE
  • Twitter: https://twitter.com/intent/tweet?text=TEXT&url=URL
  • LinkedIn: https://www.linkedin.com/sharing/share-offsite/?url=URL
  • Email: mailto:?subject=SUBJECT&body=BODY

Share Platform Integration​

  • Base URL: share.mito.ai/{token}
  • Referral URL: share.mito.ai/{token}?ref=CODE
  • CTA links: All "Try MITO for free" buttons include referral code when present
  • Context provider: ReferralProvider passes referral code to all CTAs

User Interface Elements​

Referral Page Layout​

  • Left panel (35%): Total credits earned card + referral link sharing
  • Right panel (65%): "How it works" flow diagram
  • Copy functionality: Input field + copy button + full-width copy button
  • Social buttons: Icon buttons for each platform with tooltips

Asset Sharing Dialog​

  • Referral toggle: "Include my referral code" with info tooltip
  • Default state: Enabled, persisted in IndexedDB
  • Help text: "Earn credits when people sign up" with "Learn more" link
  • Social sharing: All platforms include referral-coded URLs when enabled
  • Icon: Gift icon (GiftIcon from lucide-react)
  • Label: "Referral"
  • Badge: "Earn 3000" with coin icon
  • Access: Only shows if user has Owner/Editor role and feature flag enabled

Analytics Events to Track​

  • referral_shared: When user shares link (copy, whatsapp, twitter, linkedin, email)
  • share_link_copied: When asset share link is copied (includes has_referral boolean)
  • user_registered: Enhanced with hasReferral boolean
  • signup_cta_clicked: From shared assets with has_referral tracking
  • Credits flow: Through existing credit system analytics

Browser Storage​

  • IndexedDB database: mito-share-preferences
  • Object store: preferences
  • Key: includeReferral
  • Default value: true
  • Error handling: Graceful fallback to default on storage failures

Error States​

  • Feature disabled: Redirect to /projects if flag off
  • Insufficient permissions: Sidebar item hidden for Viewers, sharing dialog doesn't show referral toggle
  • Missing referral code: Graceful fallback to sharing without referral
  • Storage errors: Default to enabled referral inclusion

Future Enhancements Referenced​

  • Detailed tracking: Currently shows total earned only
  • Notification system: No notifications when credits are earned
  • Referral statistics: Number of signups, conversion rates, asset-specific tracking
  • Share analytics: Detailed metrics on shared asset performance
  • User guide: docs/user/account/earn-referral-credits.md
  • Asset sharing: docs/user/canvas/sharing-assets.md
  • Credit system: docs/llm/billing-voucher-system.md
  • Workspace permissions: docs/llm/workspace-project-management.md

Update Log​

  • 2026-01-29 — Updated referral credit amounts: signup credits 500→1500, subscription reward 1000→3000 (MITO-613)
  • 2026-01-24 — Added asset sharing integration with referral codes (MITO-544)
  • 2026-01-24 — Initial documentation for referral system frontend implementation