docupulse/PRICING_CONFIGURATION.md

Pricing Configuration Feature

This document describes the new configurable pricing feature that allows MASTER instances to manage pricing plans through the admin interface.

Overview

The pricing configuration feature allows administrators on MASTER instances to:

• Create, edit, and delete pricing plans
• Configure plan features, prices, and settings
• Set resource quotas for rooms, conversations, storage, and users
• Mark plans as "Most Popular" or "Custom"
• Control plan visibility and ordering
• Update pricing without code changes

Features

Pricing Plan Management

• Plan Name: Display name for the pricing plan
• Description: Optional description shown below the plan name
• Pricing: Monthly and annual prices (annual prices are typically 20% lower)
• Features: Dynamic list of features with checkmarks
• Button Configuration: Customizable button text and URL
• Plan Types: Regular plans with prices or custom plans
• Popular Plans: Mark one plan as "Most Popular" with special styling
• Active/Inactive: Toggle plan visibility
• Ordering: Control the display order of plans

Resource Quotas

• Room Quota: Maximum number of rooms allowed (0 = unlimited)
• Conversation Quota: Maximum number of conversations allowed (0 = unlimited)
• Storage Quota: Maximum storage in gigabytes (0 = unlimited)
• Manager Quota: Maximum number of manager users allowed (0 = unlimited)
• Admin Quota: Maximum number of admin users allowed (0 = unlimited)

Admin Interface

• Pricing Tab: New tab in admin settings (MASTER instances only)
• Add/Edit Modals: User-friendly forms for plan management
• Real-time Updates: Changes are reflected immediately
• Feature Management: Add/remove features dynamically
• Quota Configuration: Set resource limits for each plan
• Status Toggles: Quick switches for plan properties

Setup Instructions

1. Database Migration

Run the migrations to create the pricing_plans table and add quota fields:

# Apply the migrations
alembic upgrade head

2. Initialize Default Plans (Optional)

Run the initialization script to create default pricing plans:

# Set MASTER environment variable
export MASTER=true

# Run the initialization script
python init_pricing_plans.py

This will create four default plans with quotas:

• Starter: 5 rooms, 10 conversations, 10GB storage, 10 managers, 1 admin
• Professional: 25 rooms, 50 conversations, 100GB storage, 50 managers, 3 admins
• Enterprise: 100 rooms, 200 conversations, 500GB storage, 200 managers, 10 admins
• Custom: Unlimited everything

3. Access Admin Interface

1. Log in as an admin user on a MASTER instance
2. Go to Settings
3. Click on the "Pricing" tab
4. Configure your pricing plans

Usage

Creating a New Plan

1. Click "Add New Plan" in the pricing tab
2. Fill in the plan details:
   • Name: Plan display name
   • Description: Optional description
   • Monthly Price: Price per month
   • Annual Price: Price per month when billed annually
   • Quotas: Set resource limits (0 = unlimited)
   • Features: Add features using the "Add Feature" button
   • Button Text: Text for the call-to-action button
   • Button URL: URL the button should link to
   • Options: Check "Most Popular", "Custom Plan", or "Active" as needed
3. Click "Create Plan"

Editing a Plan

1. Click the "Edit" button on any plan card
2. Modify the plan details in the modal
3. Click "Update Plan"

Managing Plan Status

• Active/Inactive: Use the toggle switch in the plan header
• Most Popular: Check the "Most Popular" checkbox (only one plan can be popular)
• Custom Plan: Check "Custom Plan" for plans without fixed pricing

Deleting a Plan

1. Click the "Delete" button on a plan card
2. Confirm the deletion in the modal

Technical Details

Database Schema

The pricing_plans table includes:

• id: Primary key
• name: Plan name (required)
• description: Optional description
• monthly_price: Monthly price (float)
• annual_price: Annual price (float)
• features: JSON array of feature strings
• button_text: Button display text
• button_url: Button link URL
• is_popular: Boolean for "Most Popular" styling
• is_custom: Boolean for custom plans
• is_active: Boolean for plan visibility
• order_index: Integer for display ordering
• room_quota: Maximum rooms (0 = unlimited)
• conversation_quota: Maximum conversations (0 = unlimited)
• storage_quota_gb: Maximum storage in GB (0 = unlimited)
• manager_quota: Maximum managers (0 = unlimited)
• admin_quota: Maximum admins (0 = unlimited)
• created_by: Foreign key to user who created the plan
• created_at/updated_at: Timestamps

API Endpoints

• POST /api/admin/pricing-plans - Create new plan
• GET /api/admin/pricing-plans/<id> - Get plan details
• PUT /api/admin/pricing-plans/<id> - Update plan
• DELETE /api/admin/pricing-plans/<id> - Delete plan
• PATCH /api/admin/pricing-plans/<id>/status - Update plan status

Template Integration

The pricing page automatically uses configured plans:

• Falls back to hardcoded plans if no plans are configured
• Supports dynamic feature lists
• Handles custom plans without pricing
• Shows/hides billing toggle based on plan types
• Displays quota information in plan cards

Quota Enforcement

The PricingPlan model includes utility methods for quota checking:

• check_quota(quota_type, current_count): Returns True if quota allows the operation
• get_quota_remaining(quota_type, current_count): Returns remaining quota
• format_quota_display(quota_type): Formats quota for display
• get_storage_quota_bytes(): Converts GB to bytes for storage calculations

Example usage in your application:

# Check if user can create a new room
plan = PricingPlan.query.get(user_plan_id)
current_rooms = Room.query.filter_by(created_by=user.id).count()
if plan.check_quota('room_quota', current_rooms):
    # Allow room creation
    pass
else:
    # Show upgrade message
    pass

Security

• Only admin users can access pricing configuration
• Only MASTER instances can configure pricing
• All API endpoints require authentication and admin privileges
• CSRF protection is enabled for all forms

Customization

Styling

The pricing plans use the existing CSS variables:

• --primary-color: Main brand color
• --secondary-color: Secondary brand color
• --shadow-color: Card shadows

Button URLs

Configure button URLs to point to:

• Contact forms
• Payment processors
• Sales pages
• Custom landing pages

Features

Features can include:

• Storage limits
• User limits
• Feature availability
• Support levels
• Integration options

Quota Integration

To integrate quotas into your application:

1. User Plan Assignment: Associate users with pricing plans
2. Quota Checking: Use the check_quota() method before operations
3. Upgrade Prompts: Show upgrade messages when quotas are exceeded
4. Usage Tracking: Track current usage for quota calculations

Troubleshooting

Common Issues

1. Pricing tab not visible

   • Ensure you're on a MASTER instance (MASTER=true)
   • Ensure you're logged in as an admin user

2. Plans not showing on pricing page

   • Check that plans are marked as "Active"
   • Verify the database migration was applied
   • Check for JavaScript errors in browser console

3. Features not saving

   • Ensure at least one feature is provided
   • Check that feature text is not empty

4. Quota fields not working

   • Verify the quota migration was applied
   • Check that quota values are integers
   • Ensure quota fields are included in form submissions

5. API errors

   • Verify CSRF token is included in requests
   • Check that all required fields are provided
   • Ensure proper JSON formatting for features

Debugging

• Check browser console for JavaScript errors
• Review server logs for API errors
• Verify database connectivity
• Test with default plans first

Future Enhancements

Potential future improvements:

• Plan categories/tiers
• Regional pricing
• Currency support
• Promotional pricing
• Plan comparison features
• Analytics and usage tracking
• Automatic quota enforcement middleware
• Usage dashboard for quota monitoring