Subscription Admin

File: subscription-admin.markdown

Loading documentation...

# Subscription & Token Package Admin Guide

This guide provides comprehensive instructions for administrators to manage subscription plans and token packages, including Stripe integration, current functionality, and improvement recommendations.

## Table of Contents

1. [Overview](#overview)
2. [Plan Management](#plan-management)
3. [Token Package Management](#token-package-management)
4. [Stripe Integration](#stripe-integration)
5. [Current Admin Interfaces](#current-admin-interfaces)
6. [Improvement Recommendations](#improvement-recommendations)
7. [Troubleshooting](#troubleshooting)

## Overview

The Creator Platform uses a dual-billing system:
- **Subscription Plans**: Recurring monthly/yearly billing for core features
- **Token Packages**: One-time purchases for additional usage (SMS, email, transcription)

Both systems integrate with Stripe for payment processing and require proper setup in both the application and Stripe dashboard.

## Plan Management

### Creating a New Subscription Plan

#### Step 1: Access Plan Management
1. Navigate to `/admin/plans`
2. Click "Create New Plan" button
3. You'll be taken to `/admin/plans/create`

#### Step 2: Basic Plan Information
Fill in the required fields:

**Required Fields:**
- **Plan Name**: Display name (e.g., "Pro Plan", "Enterprise")
- **Slug**: URL-friendly identifier (auto-generated from name)
- **Price**: Amount in dollars (e.g., 29.99)
- **Billing Interval**: Monthly or Yearly
- **Interval Count**: Number of intervals (usually 1)
- **Stripe Plan ID**: Corresponding Stripe price ID

**Optional Fields:**
- **Description**: Plan description for users
- **Sort Order**: Display order (0 = first)
- **Active**: Whether plan is available for purchase
- **Featured**: Highlight on pricing page
- **Default Plan**: Free tier for new users

#### Step 3: Stripe Integration
**Option A: Use Existing Stripe Plan**
1. Enter the Stripe price ID manually
2. Click "Validate" to verify it exists
3. Click "Browse" to view available Stripe plans

**Option B: Create New Stripe Plan**
1. Click "🚀 Create Plan + Stripe" button
2. System will create both local plan and Stripe plan
3. Stripe plan ID will be automatically filled

#### Step 4: Plan Features
Add features that define what the plan includes:

**Feature Types:**
- **Feature**: Descriptive feature (e.g., "Priority Support")
- **Limit**: Usage limit (e.g., "100 SMS tokens")
- **Boolean**: True/false feature (e.g., "Custom Domain")

**Feature Categories:**
- **Token/Limit Features**: SMS tokens, email tokens, transcription minutes, storage, podcasts
- **Boolean Features**: Blog posts, events, contact form, subscribers, priority support, custom domain, API access, webhooks, analytics, white label, team members

**Feature Properties:**
- **Name**: Feature display name
- **Value**: Feature value (true, 100, unlimited)
- **Feature Type**: Specific feature identifier
- **Icon**: Display icon (check, star, x)
- **Highlighted**: Show prominently
- **Sort Order**: Display order

#### Step 5: Save Plan
1. Click "Create Plan" to save locally
2. Or click "🚀 Create Plan + Stripe" to create both

### Editing Existing Plans

#### Access Edit Interface
1. Go to `/admin/plans`
2. Click "Edit" button on any plan
3. Navigate to `/admin/plans/{id}/edit`

#### Edit Functionality
- **Update Basic Info**: Name, price, interval, description
- **Modify Features**: Add, remove, or edit features
- **Change Stripe Plan**: Update Stripe plan ID (with validation)
- **Toggle Status**: Activate/deactivate plan
- **Set Default**: Make plan the default for new users

#### Important Notes
- **Stripe Plan Changes**: If you change the Stripe plan ID, validate it exists
- **Feature Updates**: Changes affect existing subscribers
- **Default Plan**: Only one plan can be default at a time

### Plan Validation

#### Stripe Validation
The system validates plans against Stripe:

1. **Manual Validation**: Click "Validate Stripe" button
2. **Automatic Validation**: Runs when loading plans
3. **Validation Results**: Shows ✓ (valid) or ✗ (invalid)

#### Common Validation Issues
- **Plan Not Found**: Stripe plan ID doesn't exist
- **Plan Deleted**: Stripe plan was deleted
- **Price Mismatch**: Local price doesn't match Stripe price
- **Interval Mismatch**: Billing interval doesn't match

## Token Package Management

### Creating Token Packages

#### Step 1: Access Package Management
1. Navigate to `/admin/token-packages`
2. Click "Add New Package" button

#### Step 2: Package Configuration
Fill in the package details:

**Required Fields:**
- **Feature Type**: SMS tokens, email tokens, or transcription minutes
- **Package Name**: Display name (e.g., "100 SMS Tokens")
- **Token Amount**: Number of tokens included
- **Price**: Cost in dollars
- **Description**: Package description

**Optional Fields:**
- **Active**: Whether package is available for purchase
- **Stripe Price ID**: Corresponding Stripe price ID

#### Step 3: Stripe Integration
**Option A: Manual Stripe Price ID**
1. Enter existing Stripe price ID
2. System will validate on save

**Option B: Auto-Create Stripe Price**
1. Leave Stripe Price ID empty
2. System creates Stripe product and price automatically
3. Price ID is saved to package

#### Step 4: Save Package
1. Click "Save Package"
2. System creates package and optionally Stripe price

### Managing Token Packages

#### Package List View
- **Package Details**: Name, type, amount, price
- **Status Indicators**: Active/Inactive, Stripe validation
- **Actions**: Edit, delete, create in Stripe

#### Stripe Integration Tools
1. **View Stripe Prices**: Browse all Stripe prices
2. **Validate Stripe**: Check all packages against Stripe
3. **Update Stripe Products**: Sync product descriptions

#### Package Types Available
1. **SMS Tokens**: For sending SMS notifications
2. **Email Tokens**: For sending email notifications  
3. **Transcription Minutes**: For audio/video transcription

### Token Package Validation

#### Validation Process
1. **Stripe Price Check**: Verify price ID exists in Stripe
2. **Product Validation**: Check associated product details
3. **Price Consistency**: Ensure local price matches Stripe

#### Validation Results
- **✓ Stripe**: Package has valid Stripe price
- **✗ Stripe**: Package missing or invalid Stripe price
- **? Stripe**: Validation status unknown

## Stripe Integration

### Stripe Setup Requirements

#### Environment Variables
```env
STRIPE_KEY=pk_test_...          # Public key
STRIPE_SECRET=sk_test_...       # Secret key
STRIPE_WEBHOOK_SECRET=whsec_... # Webhook secret
```

#### Stripe Dashboard Setup
1. **Create Products**: For each plan/package
2. **Create Prices**: Recurring for plans, one-time for packages
3. **Configure Webhooks**: Point to `/api/webhook/stripe`
4. **Set Up Payment Methods**: Cards, ACH, etc.

### Plan Creation in Stripe

#### Manual Stripe Creation
1. **Create Product**:
   - Name: Plan name
   - Description: Plan description
   - Active: Yes

2. **Create Price**:
   - Product: Select created product
   - Amount: Price in cents
   - Currency: USD
   - Billing: Recurring
   - Interval: Month/Year
   - Interval Count: 1

3. **Copy Price ID**: Use as `stripe_plan_id`

#### Automated Stripe Creation
The system can create Stripe plans automatically:

```php
// StripePlanService.php
public function createPlan(array $planData): ?array
{
    // Create product
    $product = \Stripe\Product::create([
        'name' => $planData['name'],
        'description' => $planData['description'],
        'active' => true,
    ]);
    
    // Create price
    $price = \Stripe\Price::create([
        'product' => $product->id,
        'unit_amount' => (int)($planData['price'] * 100),
        'currency' => 'usd',
        'recurring' => [
            'interval' => $planData['interval'],
            'interval_count' => $planData['interval_count'],
        ],
        'active' => true,
    ]);
    
    return [
        'product_id' => $product->id,
        'price_id' => $price->id,
        'stripe_plan_id' => $price->id,
    ];
}
```

### Token Package Creation in Stripe

#### Manual Stripe Creation
1. **Create Product**:
   - Name: Package name
   - Description: Package description
   - Metadata: feature_type, amount, package_id

2. **Create Price**:
   - Product: Select created product
   - Amount: Price in cents
   - Currency: USD
   - Billing: One-time (no recurring)

3. **Copy Price ID**: Use as `stripe_price_id`

#### Automated Stripe Creation
```php
// TokenPackage.php
public function createStripePrice()
{
    // Create product
    $product = $stripe->products->create([
        'name' => $this->name,
        'description' => $this->description,
        'metadata' => [
            'feature_type' => $this->feature_type,
            'amount' => $this->amount,
            'package_id' => $this->id,
        ],
    ]);
    
    // Create price
    $price = $stripe->prices->create([
        'unit_amount' => (int)($this->price * 100),
        'currency' => 'usd',
        'product' => $product->id,
    ]);

$this->update(['stripe_price_id' => $price->id]);
}
```

### Webhook Configuration

#### Required Webhook Events
```json
{
  "events": [
    "customer.subscription.created",
    "customer.subscription.updated", 
    "customer.subscription.deleted",
    "invoice.payment_succeeded",
    "invoice.payment_failed",
    "invoice.payment_action_required",
    "charge.succeeded",
    "charge.failed",
    "charge.refunded"
  ]
}
```

#### Webhook Endpoint
- **URL**: `https://yourdomain.com/api/webhook/stripe`
- **Secret**: Use webhook secret from environment
- **Tolerance**: 300 seconds (5 minutes)

## Current Admin Interfaces

### Plan Management Interface (`/admin/plans`)

#### Current Functionality
✅ **Plan List View**
- Display all plans with basic info
- Status indicators (active/inactive)
- Stripe validation status
- Quick actions (edit, delete)

✅ **Plan Creation (`/admin/plans/create`)**
- Form-based plan creation
- Auto-slug generation
- Feature management
- Stripe plan ID validation
- Auto-create Stripe plan option

✅ **Plan Editing (`/admin/plans/{id}/edit`)**
- Edit existing plans
- Modify features
- Update Stripe integration
- Toggle plan status

✅ **Stripe Integration**
- Validate Stripe plan IDs
- Browse Stripe plans
- Auto-create Stripe plans
- Validation status display

#### Current Limitations
❌ **No Bulk Operations**: Can't edit multiple plans at once
❌ **Limited Feature Templates**: No pre-built feature sets
❌ **No Plan Comparison**: Can't easily compare plans
❌ **No Usage Analytics**: No plan usage statistics
❌ **No Migration Tools**: Can't easily migrate users between plans

### Token Package Interface (`/admin/token-packages`)

#### Current Functionality
✅ **Package List View**
- Display all packages by type
- Status indicators
- Stripe validation status
- Quick actions

✅ **Package Creation**
- Form-based package creation
- Feature type selection
- Price and amount configuration
- Auto-create Stripe price option

✅ **Stripe Integration**
- Validate Stripe price IDs
- Browse Stripe prices
- Auto-create Stripe prices
- Update product descriptions

✅ **Validation Tools**
- Validate all packages against Stripe
- View Stripe price details
- Sync product information

#### Current Limitations
❌ **No Package Templates**: No pre-built package sets
❌ **No Bulk Operations**: Can't edit multiple packages
❌ **No Usage Analytics**: No package purchase statistics
❌ **No Price History**: No tracking of price changes
❌ **No Package Bundles**: Can't create multi-package deals

## Improvement Recommendations

### Plan Management Enhancements

#### 1. Plan Templates
**Current Issue**: Admins must manually configure each plan
**Solution**: Pre-built plan templates

```php
// Plan templates
$templates = [
    'starter' => [
        'name' => 'Starter Plan',
        'price' => 9.99,
        'features' => [
            ['name' => 'SMS Tokens', 'value' => '50', 'type' => 'limit'],
            ['name' => 'Email Tokens', 'value' => '100', 'type' => 'limit'],
            ['name' => 'Blog Posts', 'value' => 'true', 'type' => 'boolean'],
        ]
    ],
    'pro' => [
        'name' => 'Pro Plan', 
        'price' => 29.99,
        'features' => [
            ['name' => 'SMS Tokens', 'value' => '200', 'type' => 'limit'],
            ['name' => 'Email Tokens', 'value' => '500', 'type' => 'limit'],
            ['name' => 'Custom Domain', 'value' => 'true', 'type' => 'boolean'],
        ]
    ]
];
```

#### 2. Plan Comparison Tool
**Current Issue**: Hard to compare plan features
**Solution**: Side-by-side comparison interface

```html

<table class="plan-comparison">
    <thead>
        <tr>
            <th>Feature</th>
            <th>Starter</th>
            <th>Pro</th>
            <th>Enterprise</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>SMS Tokens</td>
            <td>50</td>
            <td>200</td>
            <td>Unlimited</td>
        </tr>
    </tbody>
</table>
```

#### 3. Usage Analytics Dashboard
**Current Issue**: No visibility into plan usage
**Solution**: Analytics dashboard

```php
// Plan analytics
$analytics = [
    'total_subscribers' => Plan::withCount('subscriptions')->get(),
    'revenue_by_plan' => SubscriptionPayment::groupBy('plan_id')->sum('amount'),
    'churn_rate' => $this->calculateChurnRate(),
    'upgrade_rate' => $this->calculateUpgradeRate(),
];
```

#### 4. Bulk Operations
**Current Issue**: Can't edit multiple plans efficiently
**Solution**: Bulk edit interface

```javascript
// Bulk edit functionality
function bulkEditPlans() {
    const selectedPlans = getSelectedPlans();
    const changes = getBulkChanges();
    
    selectedPlans.forEach(plan => {
        updatePlan(plan.id, changes);
    });
}
```

#### 5. Plan Migration Tools
**Current Issue**: No easy way to migrate users between plans
**Solution**: Migration wizard

```php
// Plan migration service
class PlanMigrationService {
    public function migrateUsers($fromPlanId, $toPlanId, $options = []) {
        $users = User::where('current_plan_id', $fromPlanId)->get();
        
        foreach ($users as $user) {
            $this->migrateUser($user, $toPlanId, $options);
        }
    }
}
```

### Token Package Enhancements

#### 1. Package Templates
**Current Issue**: Manual package configuration
**Solution**: Pre-built package templates

```php
// Package templates
$templates = [
    'sms_starter' => [
        'name' => '100 SMS Tokens',
        'amount' => 100,
        'price' => 5.00,
        'feature_type' => 'sms_tokens'
    ],
    'email_pro' => [
        'name' => '500 Email Tokens', 
        'amount' => 500,
        'price' => 15.00,
        'feature_type' => 'email_tokens'
    ]
];
```

#### 2. Package Bundles
**Current Issue**: Can't create multi-package deals
**Solution**: Bundle creation interface

```php
// Package bundles
class PackageBundle {
    public $name;
    public $packages; // Array of package IDs with quantities
    public $discount; // Percentage discount
    public $stripe_price_id;
}
```

#### 3. Usage Analytics
**Current Issue**: No package purchase analytics
**Solution**: Analytics dashboard

```php
// Package analytics
$analytics = [
    'popular_packages' => TokenPurchase::groupBy('feature_type')->count(),
    'revenue_by_type' => TokenPurchase::groupBy('feature_type')->sum('purchase_price'),
    'average_purchase' => TokenPurchase::avg('purchase_price'),
];
```

#### 4. Price History Tracking
**Current Issue**: No tracking of price changes
**Solution**: Price history table

```sql
CREATE TABLE package_price_history (
    id BIGINT PRIMARY KEY,
    package_id BIGINT,
    old_price DECIMAL(8,2),
    new_price DECIMAL(8,2),
    changed_at TIMESTAMP,
    changed_by BIGINT
);
```

#### 5. Auto-Pricing
**Current Issue**: Manual price setting
**Solution**: Dynamic pricing based on usage

```php
// Auto-pricing service
class AutoPricingService {
    public function suggestPrice($featureType, $amount) {
        $usage = $this->getUsageData($featureType);
        $cost = $this->calculateCost($amount);
        $margin = $this->getTargetMargin();
        
        return $cost * (1 + $margin);
    }
}
```

### General Admin Interface Improvements

#### 1. Dashboard Overview
**Current Issue**: No central admin dashboard
**Solution**: Comprehensive dashboard

```html

<div class="admin-dashboard">
    <div class="stats-grid">
        <div class="stat-card">
            <h3>Total Subscribers</h3>
            <p>{{ $totalSubscribers }}</p>
        </div>
        <div class="stat-card">
            <h3>Monthly Revenue</h3>
            <p>${{ $monthlyRevenue }}</p>
        </div>
        <div class="stat-card">
            <h3>Token Sales</h3>
            <p>{{ $tokenSales }}</p>
        </div>
    </div>
</div>
```

#### 2. Search and Filtering
**Current Issue**: Limited search capabilities
**Solution**: Advanced search interface

```javascript
// Advanced search
function searchPlans(filters) {
    const params = new URLSearchParams({
        search: filters.search,
        status: filters.status,
        price_min: filters.priceMin,
        price_max: filters.priceMax,
        feature_type: filters.featureType
    });
    
    return fetch(`/api/admin/plans?${params}`);
}
```

#### 3. Export/Import Tools
**Current Issue**: No data export/import
**Solution**: CSV/JSON export/import

```php
// Export functionality
public function exportPlans() {
    $plans = Plan::with('features')->get();
    
    return response()->json($plans)
        ->header('Content-Disposition', 'attachment; filename="plans.json"');
}
```

#### 4. Audit Logging
**Current Issue**: No tracking of admin changes
**Solution**: Comprehensive audit log

```php
// Audit logging
class AdminAuditLog {
    public function log($action, $model, $changes, $admin) {
        return AuditLog::create([
            'admin_id' => $admin->id,
            'action' => $action,
            'model_type' => get_class($model),
            'model_id' => $model->id,
            'changes' => json_encode($changes),
            'ip_address' => request()->ip(),
        ]);
    }
}
```

#### 5. Role-Based Access
**Current Issue**: All admins have full access
**Solution**: Granular permissions

```php
// Admin permissions
$permissions = [
    'plans.view' => 'View plans',
    'plans.create' => 'Create plans', 
    'plans.edit' => 'Edit plans',
    'plans.delete' => 'Delete plans',
    'packages.view' => 'View packages',
    'packages.create' => 'Create packages',
    'packages.edit' => 'Edit packages',
    'packages.delete' => 'Delete packages',
];
```

## Troubleshooting

### Common Issues

#### 1. Stripe Plan Not Found
**Symptoms**: Validation shows "✗ Stripe" status
**Causes**: 
- Plan ID mistyped
- Plan deleted in Stripe
- Wrong Stripe environment (test vs live)

**Solutions**:
1. Verify plan ID in Stripe dashboard
2. Check Stripe environment settings
3. Recreate plan in Stripe if deleted

#### 2. Webhook Failures
**Symptoms**: Subscription status not updating
**Causes**:
- Incorrect webhook URL
- Missing webhook secret
- Webhook not configured

**Solutions**:
1. Verify webhook URL in Stripe dashboard
2. Check webhook secret in environment
3. Test webhook endpoint

#### 3. Payment Failures
**Symptoms**: Users can't subscribe
**Causes**:
- Invalid payment method
- Insufficient funds
- Stripe account issues

**Solutions**:
1. Check Stripe dashboard for errors
2. Verify payment method configuration
3. Test with Stripe test cards

#### 4. Feature Access Issues
**Symptoms**: Users can't access features
**Causes**:
- Plan not active
- Feature not included in plan
- Usage limits exceeded

**Solutions**:
1. Check plan status and features
2. Verify user's current plan
3. Check usage limits

### Debug Tools

#### 1. Stripe Logs
```php
// Enable Stripe logging
\Stripe\Stripe::setLogger(new \Monolog\Logger('stripe'));
```

#### 2. Webhook Testing
```bash
# Test webhook locally
stripe listen --forward-to localhost:8000/api/webhook/stripe
```

#### 3. Plan Validation
```php
// Manual plan validation
$stripeService = app(StripePlanService::class);
$isValid = $stripeService->planExists('price_1234567890');
```

---

*This guide covers all aspects of subscription and token package administration. For technical implementation details, refer to the specific controller and service files.*

Subscription Admin

Subscription Admin

📝 Page Notes

Add New Note