Free Trial System

Free Trial System

3-day free trial with $10 credits for new users

---

Overview

New users automatically receive:

• 3-day trial period
• $10 free credits
• 1000 request limit
• 100K token limit
• Auto-conversion tracking

---

How It Works

1. User registers → Trial starts automatically
2. Trial period: 3 days from signup
3. Free credits: $10 (1000 credits)
4. Usage tracked separately from paid credits
5. After 3 days or usage limit → Trial ends
6. User must add payment method to continue

---

Trial Limits

Metric	Limit
Duration	3 days
Credits	$10 (1000 credits)
Requests	1000 total
Tokens	100,000 total
Expiration	Auto-expires after 3 days

---

Quick Reference

Check Trial Status

curl http://localhost:8000/trials/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "is_trial": true,
  "trial_start": "2024-12-15T10:00:00Z",
  "trial_end": "2024-12-18T10:00:00Z",
  "days_remaining": 2,
  "credits_remaining": 8.50,
  "requests_used": 123,
  "requests_remaining": 877,
  "tokens_used": 45000,
  "tokens_remaining": 55000,
  "has_converted": false
}

Start Trial (Auto)

Trial automatically starts on user registration:

curl -X POST http://localhost:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "email": "user@example.com",
    "auth_method": "email"
  }'

---

API Endpoints

1. Get Trial Status

GET /trials/status

Returns current trial information.

2. Start Trial (Manual)

POST /trials/start

Manually start trial (usually automatic).

3. Convert Trial

POST /trials/convert

Convert to paid account (after payment).

---

Trial Data

In API Keys Table

-- Trial fields in api_keys_new
is_trial BOOLEAN DEFAULT true
trial_start_date TIMESTAMP
trial_end_date TIMESTAMP
trial_used_tokens INTEGER DEFAULT 0
trial_used_requests INTEGER DEFAULT 0
trial_used_credits NUMERIC DEFAULT 0
trial_max_tokens INTEGER DEFAULT 100000
trial_max_requests INTEGER DEFAULT 1000
trial_credits NUMERIC DEFAULT 10.0
trial_converted BOOLEAN DEFAULT false
subscription_status TEXT DEFAULT 'trial'

In Users Table

has_made_first_purchase BOOLEAN DEFAULT false
trial_converted_at TIMESTAMP

---

Trial Lifecycle

Phase 1: Active Trial

• is_trial = true
• subscription_status = 'trial'
• Credits deducted from trial_credits
• Usage tracked separately

Phase 2: Trial Expired

• 3 days passed OR limits reached
• API requests return: 402 Payment Required
• Message: "Trial expired. Please add payment method"

Phase 3: Converted

• User makes first purchase
• trial_converted = true
• subscription_status = 'active'
• Switch to paid credits

---

Usage Tracking

Per Request

# Check trial limits
if api_key.is_trial:
    if api_key.trial_used_requests >= api_key.trial_max_requests:
        return 402  # Trial limit reached

    if api_key.trial_used_tokens >= api_key.trial_max_tokens:
        return 402  # Token limit reached

    # Deduct from trial credits
    api_key.trial_used_credits += cost
    api_key.trial_used_requests += 1
    api_key.trial_used_tokens += tokens

Credit Deduction

1. Check if trial active
2. Deduct from trial_credits
3. If trial_credits exhausted → trial ends
4. Track in trial_used_credits

---

Conversion

Auto-Conversion

Triggered by first purchase webhook:

if user.has_made_first_purchase == False:
    # User was on trial
    api_key.trial_converted = True
    api_key.subscription_status = 'active'
    user.has_made_first_purchase = True
    user.trial_converted_at = NOW()

Benefits After Conversion

• Unlimited requests (plan-based)
• Higher token limits
• Access to all models
• Priority support
• No expiration

---

Monitoring

Trial Statistics

-- Active trials
SELECT COUNT(*) as active_trials
FROM api_keys_new
WHERE is_trial = true
  AND trial_end_date > NOW();

-- Conversion rate
SELECT
  COUNT(*) FILTER (WHERE trial_converted = true) * 100.0 /
  COUNT(*) as conversion_rate
FROM api_keys_new
WHERE is_trial = true;

-- Average trial usage
SELECT
  AVG(trial_used_credits) as avg_credits,
  AVG(trial_used_requests) as avg_requests,
  AVG(trial_used_tokens) as avg_tokens
FROM api_keys_new
WHERE is_trial = true;

---

Edge Cases

Trial Expired

{
  "error": "Trial expired",
  "message": "Your 3-day trial has ended. Add payment method to continue.",
  "trial_end": "2024-12-18T10:00:00Z",
  "upgrade_url": "/pricing"
}

Limits Reached

{
  "error": "Trial limit reached",
  "message": "You've used all trial credits. Upgrade to continue.",
  "used": 10.0,
  "limit": 10.0
}

Already Converted

Can't start new trial if already converted.

---

Configuration

Adjust Trial Limits

Edit src/db/api_keys.py:

TRIAL_CONFIG = {
    "duration_days": 3,
    "credits": 10.0,
    "max_requests": 1000,
    "max_tokens": 100000
}

Extend Trial

-- Extend specific user's trial
UPDATE api_keys_new
SET trial_end_date = trial_end_date + INTERVAL '3 days'
WHERE user_id = 123 AND is_trial = true;

---

Best Practices

For Users

1. Test thoroughly: Use trial to validate integration
2. Monitor usage: Check remaining credits
3. Plan upgrade: Don't wait until last day
4. Read limits: Understand request/token limits

For Admins

1. Track conversions: Monitor conversion funnel
2. Optimize limits: Balance generosity and cost
3. Send reminders: Email before trial expires
4. Analyze usage: What features convert best?
5. Support trials: Help users succeed

---

Notifications

Trial Started

Welcome to Gatewayz!
Your 3-day trial includes $10 free credits.
Expires: Dec 18, 2024

Trial Ending (1 day left)

Trial ending soon!
1 day remaining
Credits left: $3.50
Upgrade now: /pricing

Trial Expired

Trial expired
Add payment to continue using Gatewayz

---

Related Documentation

• Stripe Integration - Payment after trial
• Subscription Plans - Paid plans
• Referral System - Bonus credits

---

Last Updated: December 2024 Status: Production Ready

---

Related

• Subscription-Plans — What happens after trial ends
• Stripe-Integration — Payment when converting from trial
• Coupon-System — Coupons can extend trial credits
• Delta Report — P0-7: Trial config mismatch ($5 vs $10)