Billing & Subscriptions
Relevant source files
The following files were used as context for generating this wiki page:
The Billing & Subscription system in ALwrity is a comprehensive usage-based framework designed to track API consumption, manage subscription tiers, and enforce usage limits across multiple AI providers. It integrates backend monitoring middleware with real-time frontend dashboards to provide transparent cost tracking and automated limit enforcement.
Sources: backend/BILLING_SYSTEM_INTEGRATION.md:3-6, backend/SUBSCRIPTION_SYSTEM_README.md:3-6
System Architecture & Logic
The system operates on a usage-based billing model that calculates costs in real-time based on token consumption (input and output) and flat-rate API calls. It employs a multi-tenant architecture to isolate usage logs and subscription assignments for individual users.
Sources: backend/BILLING_SYSTEM_INTEGRATION.md:14-22, backend/SUBSCRIPTION_SYSTEM_README.md:9-15
Data Flow for Usage Tracking
The following diagram illustrates how an API request is intercepted by the monitoring middleware, validated against subscription limits, and logged for billing purposes.
The system automatically tracks API calls, token usage, costs, response times, and error rates.
Sources: backend/BILLING_SYSTEM_INTEGRATION.md:58-64, backend/SUBSCRIPTION_SYSTEM_README.md:120-138
Database Schema
The billing system utilizes a SQLite database (PostgreSQL ready) with several core tables to manage plans, usage, and alerts.
| Table Name | Purpose |
|---|---|
subscription_plans | Defines tiers (Free, Basic, Pro, Enterprise) and their respective limits. |
user_subscriptions | Maps users to specific subscription assignments. |
api_usage_logs | Stores detailed records of every API call made, including token counts and costs. |
usage_summaries | Aggregates usage statistics per user per billing period for performance. |
api_provider_pricing | Contains the per-token cost configuration for each AI provider. |
usage_alerts | Stores notifications triggered at 80%, 90%, and 100% usage thresholds. |
billing_history | Historical records of past billing cycles. |
Sources: backend/BILLING_SYSTEM_INTEGRATION.md:33-41, backend/SUBSCRIPTION_SYSTEM_README.md:23-31, backend/test/verify_billing_setup.py:59-66
Subscription Plans & Pricing
ALwrity offers four primary subscription tiers with varying limits on API calls and monthly costs.
Tier Definitions
| Plan | Monthly Price | API Limits | Monthly Cost Limit |
|---|---|---|---|
| Free | $0 | 100 Gemini calls | N/A |
| Basic | $29 | 1k Gemini / 500 OpenAI calls | $50 |
| Pro | $79 | 5k Gemini / 2.5k OpenAI calls | $150 |
| Enterprise | $199 | Unlimited (subject to cost limit) | $500 |
Sources: backend/BILLING_SYSTEM_INTEGRATION.md:79-84, backend/SUBSCRIPTION_SYSTEM_README.md:46-65
Provider Pricing Configuration
Costs are calculated based on specific provider models. The PricingService handles these calculations using the following default rates:
| Provider | Model | Input Cost (per 1M tokens) | Output Cost (per 1M tokens) |
|---|---|---|---|
| Gemini | 2.5 Pro | $1.25 | $10.00 |
| Gemini | 2.5 Flash | $0.125 | $0.375 |
| OpenAI | GPT-4 | $30.00 | $60.00 |
| Anthropic | Claude-3 | $8.00 | $24.00 |
Sources: backend/BILLING_SYSTEM_INTEGRATION.md:70-76, backend/SUBSCRIPTION_SYSTEM_README.md:70-74
API Endpoints
The system provides several endpoints for managing subscriptions and viewing usage data.
| Method | Endpoint | Description |
|---|---|---|
GET | /api/subscription/plans | Retrieves all available subscription tiers. |
GET | /api/subscription/usage/{user_id} | Returns current monthly stats for a user. |
GET | /api/subscription/dashboard/{user_id} | Aggregated data for the frontend billing UI. |
GET | /api/subscription/pricing | Returns the current price-per-token for all providers. |
GET | /api/subscription/alerts/{user_id} | Retrieves usage threshold warnings. |
Sources: backend/BILLING_SYSTEM_INTEGRATION.md:48-53, backend/SUBSCRIPTION_SYSTEM_README.md:83-93, backend/README.md:104-108
Frontend Integration
The BillingOverview component provides a real-time visualization of a user's subscription status. It tracks:
- Total Monthly Cost: Displayed as a currency value with a progress bar against the plan limit.
- Usage Percentages: Specific gauges for Gemini usage and overall error rates.
- Status Indicators: Dynamic chips showing "Active", "Warning" (80%+ usage), or "Limit Reached".
Sources: frontend/src/components/billing/BillingOverview.tsx:55-80, frontend/src/components/billing/BillingOverview.tsx:135-155
Setup & Verification
Integration into the ALwrity platform is managed by the start_alwrity_backend.py script, which initializes billing tables and verifies provider pricing on startup.
- Table Creation: Handled by
backend/scripts/create_billing_tables.py. - Verification: The
verify_billing_setup.pyscript checks for the existence of required files (Models, Services, API) and validates database records. - Integration: The system is injected into the FastAPI app via
monitoring_middleware.pyand thesubscription_router.
Sources: backend/test/verify_billing_setup.py:90-110, backend/BILLING_SYSTEM_INTEGRATION.md:9-15
Summary
The Billing & Subscription system provides a robust foundation for commercializing the ALwrity platform. By combining real-time middleware tracking with a modular pricing service, the system ensures that AI provider costs are strictly monitored and enforced according to user-specific plan tiers.