Billing & Payment Processing

Overview

The MECLABS AI platform uses a tiered subscription model with Stripe integration for payment processing. The system implements a three-tier structure (Build, Sell, Scale) with monthly and annual billing options (15% discount for annual), credit-based usage tracking, re-sellable Customer Kits, and flexible organization seat management.

Core Components

Subscription Plans

Plan	Monthly Price	Annual Price (15% discount)	Org Members	Customer Kits	Pooled Credits	Key Platform Unlocks
Build	$585	$495/mo ($5,940/yr)	5	0	6,000 MLC	MVP build, lead-gen ADS, Agent Builder
Sell	$1,170	$995/mo ($11,940/yr)	12	10	18,000 MLC	Stripe connector, SuperFunnel Builder
Scale	$3,525	$2,995/mo ($35,940/yr)	30	45	75,000 MLC	MCP connector, testing suite, analytics at scale

Credit System (MLC)

• Billing unit: 1 MLC = $0.01 raw compute cost
• Top-up pricing: $0.0135 per MLC (35% markup over raw cost)
• Credit expiry: 90 days for all credits (plan-included, Customer Kit credits, and top-ups)
• Overage handling: Automatic draw from pooled credits at $0.0135/MLC rate
• Credit allocation: Platform plans include pooled credits; Customer Kits include dedicated 1,000 MLC each

Customer Kits

Re-sellable external seats for end customers:

• Base price: $20/kit/month (to partners/organizations)
• Includes: 1 login + 1,000 MLC credits (isolated from organization pool)
• Partner economics: At $49 resale price, partners achieve ~59% gross margin ($29 profit/kit)
• Use case: Monetizing Agent Delivery System (ADS) deployments to external users

Organization Members (Org Seats)

Internal team collaboration seats:

• Add-on price: $80/seat/month (beyond plan inclusions)
• Credit usage: Draws from organization's pooled credits
• Credit allocation: No additional credits included with seat add-ons
• Base inclusions: Build (5), Sell (12), Scale (30) seats

Payment Processing Architecture

Stripe Integration

Core payment processing components:

1. Subscription Management (server/routes/stripe-subscription.ts):

   • Create, upgrade, downgrade, cancel, and renew subscriptions
   • Handle trial periods (21-day standard or $1 trial)
   • Process one-time setup fees for trial conversions
   • Proration handling via always_invoice behavior

2. Customer Management:

   • Automatic Stripe customer creation linked to user accounts
   • Default payment method management
   • Invoice settings and billing address configuration

3. Price Lookup Keys:

   • Standard format: {plan}_{period} (e.g., build_monthly, sell_yearly)
   • Trial setup fee: {plan}_one_dollar_setup_fee
   • Add-on pricing: org_seat_addon, customer_kit_addon

Subscription Lifecycle

Creation Flow

1. User selects plan (Build/Sell/Scale) and billing period (monthly/annual)
2. System creates or retrieves Stripe customer record
3. Creates subscription with trial period if applicable (21-day or $1 trial)
4. Updates organization records with subscription details
5. Allocates included seats and credits
6. Updates JWT claims for feature access

Upgrade/Downgrade Flow

1. Validates user permissions (must be organization owner)
2. Calculates proration for plan changes
3. Updates Stripe subscription with new price ID
4. Adjusts seat and credit allocations
5. Updates organization metadata and feature access
6. Triggers webhook for real-time sync

Trial Management

Trial options aligned with customer acquisition strategy:

• 21-Day Build Access Pass: Standard trial, no upfront payment
• $1 Hackathon Trial: 21 days with $1 setup fee (lead generation)
• Voucher Gate: $10,000 funded build converting to subscription at day 21

Trial tracking:

• Stripe subscription status: trialing
• Database: stripeTrialIds array for multiple trial tracking
• Metadata: onboarding_type for conversion attribution

Database Schema

Organization Document

{
  plan: "build" | "sell" | "scale",
  period: "monthly" | "yearly",
  stripeSubscriptionId: string,
  stripeSubscriptionStatus: SubscriptionStatus,
  stripeCustomerId: string,
  ownerId: string,
  memberIds: string[],
  customerKitIds?: string[],
  creditBalance: number, // Current MLC balance
  expires?: Timestamp, // For admin-managed trials
  metadata?: {
    annualBillingStartDate?: Timestamp,
    priceLockExpiry?: Timestamp // 2-year price lock
  }
}

Team Document (Legacy Support)

{
  orgId?: string, // Organization association
  plan?: "essential", // Legacy team-specific plan
  stripeSubscriptionId?: string,
  stripeSubscriptionStatus?: SubscriptionStatus
}

Credit Ledger

{
  type: "plan" | "kit" | "topup" | "usage",
  orgId: string,
  amount: number, // Positive for credits, negative for usage
  balance: number, // Running balance after transaction
  source?: "subscription" | "customer_kit" | "manual_topup",
  modelId?: string, // For usage tracking
  created: Timestamp,
  expires: Timestamp, // 90 days from creation
  metadata?: {
    stripeInvoiceId?: string,
    kitId?: string,
    userId?: string
  }
}

User Document

{
  stripeCustomerId: string,
  organizations: string[], // Organization memberships
  customerKits?: string[], // Assigned Customer Kit IDs
  lastOrgId?: string,
  role: "owner" | "member" | "kit_user"
}

Access Control & Permissions

Subscription Management

• Create/Modify: Restricted to organization owners
• View: Available to all organization members
• Cancel: Owner-only with 30-day notice period for annual plans

Credit Access Hierarchy

• Organization pooled credits: Shared by all Org Members
• Customer Kit credits: Isolated 1,000 MLC per kit, non-transferable
• Top-up credits: Added to organization pool, subject to 90-day expiry
• Usage priority: Plan credits → Top-up credits → Overage billing

Webhook Processing

Stripe event handlers (server/api-v1/callback-stripe.ts):

• invoice.payment_succeeded: Activates subscriptions, allocates credits
• invoice.payment_failed: Initiates dunning process, sends notifications
• customer.subscription.updated: Syncs plan changes, updates features
• customer.subscription.deleted: Handles cancellations, preserves data for 30 days
• invoice.created: Pre-bills for usage overages
• payment_method.attached: Updates default payment method

Revenue Optimization

Pricing Psychology

• Annual discount: 15% reduction positions at optimal B2B SaaS sweet spot
• Price anchoring: Monthly prices shown first ($585/$1,170/$3,525)
• Two-year price lock: Reduces churn for annual subscribers
• Net-30 terms: Available exclusively for annual contracts

Growth Triggers

Trigger Point	Build → Sell	Sell → Scale
Need payment processing	Stripe connector unlock	—
Customer Kits exhausted	>0 kits triggers upgrade	>10 kits triggers upgrade
Org seats exceeded	>5 seats	>12 seats
Credit consumption	6k→18k MLC	18k→75k MLC
Advanced features	SuperFunnel Builder	MCP connector, testing suite

Partner Economics

• Commission structure: 40% lifetime on referred subscriptions
• Customer Kit margin: Partners keep 100% of markup above $20 base cost
• White-label option: Custom branding for ADS deployments at Scale tier

Technical Implementation

Credit Tracking Architecture

• Real-time deduction: Credits consumed per API call with model-specific rates
• Ledger system: Append-only transaction log for audit trail
• Balance caching: Redis cache for high-frequency balance checks
• Expiry job: Daily cron to mark expired credits

Model Pricing Matrix

Model	Raw Cost/1M tokens	MLC Consumed	Customer Cost
GPT-4o mini	$0.75	75	$1.01
GPT-4o	$12.50	1,250	$16.88
Claude 3.5 Sonnet	$15.00	1,500	$20.25
Gemini 1.5 Pro	$7.00	700	$9.45

Payment Processing

• Primary: Credit/debit cards via Stripe
• Enterprise: ACH/wire for annual contracts >$10k
• Retry logic: 3 attempts over 7 days for failed payments
• Dunning: Email sequence at days 1, 3, 7, 14, 28

State Synchronization

• Source of truth: Stripe for subscription status
• Local cache: Firestore for feature flags and limits
• JWT claims: Updated within 60 seconds of subscription changes
• Webhook reliability: Idempotent processing with event deduplication

Compliance & Reporting

Tax Handling

• US sales tax: Calculated via Stripe Tax based on customer location
• International VAT: Reverse charge mechanism for B2B EU customers
• Invoice requirements: Includes tax ID, billing address, itemized charges

Financial Reporting

• MRR tracking: Monthly recurring revenue by plan tier
• Churn analysis: Cohort-based retention metrics
• Credit utilization: Breakage rates and consumption patterns
• Partner commissions: Monthly reconciliation of 40% lifetime payouts

Audit Trail

• Subscription changes: Complete history with user attribution
• Credit transactions: Immutable ledger with source tracking
• Payment events: Stripe webhook logs retained for 90 days
• Access logs: Billing action audit for compliance