Credit System for API Usage
The credit system allows users to consume third-party API services through a unified credit-based payment model. Credits are allocated through subscriptions and can be used for various services like OpenAI API calls, 3D model generation, and agent usage.
Overview
The credit system consists of the following components:
- Service Cost Management: Admin-configurable costs for third-party services
- Credit Allocation: Credits included with subscription plans
- Credit Usage Tracking: Tracking and deducting credits for API usage
- Credit Purchasing: Allowing users to purchase additional credits
Database Schema
Service Costs Table
Stores the costs of third-party API services:
CREATE TABLE service_costs (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
service_name TEXT NOT NULL,
service_key TEXT NOT NULL UNIQUE,
cost_per_unit DECIMAL(10, 6) NOT NULL,
unit_type TEXT NOT NULL,
multiplier DECIMAL(10, 2) NOT NULL DEFAULT 1.0,
description TEXT,
is_active BOOLEAN NOT NULL DEFAULT true,
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
);
User Credits Table
Stores user credit balances:
CREATE TABLE user_credits (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
balance INTEGER NOT NULL DEFAULT 0,
last_updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
UNIQUE(user_id)
);
Credit Transactions Table
Tracks credit transactions:
CREATE TABLE credit_transactions (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
amount INTEGER NOT NULL, -- Positive for additions, negative for usage
balance INTEGER NOT NULL, -- Balance after transaction
description TEXT NOT NULL,
type TEXT NOT NULL CHECK (type IN ('purchase', 'usage', 'refund', 'expiration', 'adjustment', 'subscription')),
service_key TEXT, -- Key of the service that used the credits
service_usage JSONB, -- Details of service usage
metadata JSONB,
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
expires_at TIMESTAMP WITH TIME ZONE
);
Core Components
Service Cost Model
The serviceCost.model.ts
file provides functions for managing service costs:
getAllServiceCosts()
: Get all service costsgetServiceCostByKey(serviceKey)
: Get service cost by keycreateServiceCost(serviceCost)
: Create a new service costupdateServiceCost(id, updates)
: Update a service costdeleteServiceCost(id)
: Delete a service costcalculateCreditCost(serviceKey, units)
: Calculate credit cost for service usage
User Credit Model
The userCredit.model.ts
file provides functions for managing user credits:
getUserCredit(userId)
: Get user credit balanceaddCredits(userId, amount, description, type, metadata)
: Add credits to useruseCredits(userId, amount, description, type, metadata)
: Use credits from useruseServiceCredits(userId, serviceKey, units, description, metadata)
: Use credits for a specific servicegetCreditTransactions(userId, limit, offset)
: Get credit transactions for a usergetCreditUsageByService(userId, limit, offset)
: Get credit usage by servicehasEnoughCredits(userId, amount)
: Check if user has enough creditsinitializeUserCredit(userId, initialBalance)
: Initialize user credit if it doesn't exist
Credit Service
The creditService.ts
file provides a unified interface for credit management:
hasEnoughCreditsForService(userId, serviceKey, units)
: Check if user has enough credits for a serviceuseServiceCredits(userId, serviceKey, units, description, metadata)
: Use credits for a servicegetAllServiceCosts()
: Get all service costsgetServiceCostByKey(serviceKey)
: Get service cost by keycreateServiceCost(serviceCost)
: Create a new service costupdateServiceCost(id, updates)
: Update a service costdeleteServiceCost(id)
: Delete a service costgetUserCreditUsageByService(userId, limit, offset)
: Get user credit usage by servicegetUserCreditBalance(userId)
: Get user credit balanceaddCreditsToUser(userId, amount, description, type, metadata)
: Add credits to userinitializeUserCredit(userId, initialBalance)
: Initialize user credit if it doesn't exist
API Credit Middleware
The apiCredit.middleware.ts
file provides middleware for checking and deducting credits for API usage:
checkApiCredits(serviceKey, estimatedUnits)
: Check if user has enough credits for an API requesttrackApiUsage(req, actualUnits, additionalMetadata)
: Track actual API usage and deduct credits
Integration with Subscription System
The credit system is integrated with the subscription system in the following ways:
- Subscription Tiers: Each subscription tier includes a specified number of credits
- Subscription Creation: Credits are allocated when a user subscribes to a plan
- Subscription Renewal: Credits are replenished on subscription renewal
- Credit Purchasing: Users can purchase additional credits beyond what's included in their subscription
API Endpoints
User Endpoints
GET /api/subscriptions/credits
: Get user's credit balanceGET /api/subscriptions/credits/transactions
: Get user's credit transactionsGET /api/subscriptions/credits/usage-by-service
: Get credit usage by servicePOST /api/subscriptions/credits/purchase
: Purchase creditsPOST /api/subscriptions/credits/use
: Use creditsPOST /api/subscriptions/credits/use-service
: Use credits for a specific serviceGET /api/subscriptions/service-costs
: Get all service costs
Admin Endpoints
GET /api/admin/service-costs
: Get all service costsGET /api/admin/service-costs/:id
: Get service cost by IDPOST /api/admin/service-costs
: Create a new service costPUT /api/admin/service-costs/:id
: Update a service costDELETE /api/admin/service-costs/:id
: Delete a service cost
Usage Examples
Checking and Deducting Credits for API Usage
// In an API route handler
import apiCreditMiddleware from '../middleware/apiCredit.middleware';
// Check if user has enough credits for OpenAI GPT-4 usage
router.post(
'/generate-text',
authMiddleware,
apiCreditMiddleware.checkApiCredits('openai.gpt-4', 10), // Estimated 10 units
async (req, res) => {
try {
// Process the request
const result = await openaiService.generateText(req.body.prompt);
// Track actual usage (e.g., based on tokens used)
await apiCreditMiddleware.trackApiUsage(
req,
result.usage.totalTokens / 1000, // Convert tokens to units
{ model: 'gpt-4', promptTokens: result.usage.promptTokens, completionTokens: result.usage.completionTokens }
);
res.status(200).json();
} catch (error) {
// Handle error
res.status(500).json({ success: false, error: error.message });
}
}
);
Adding Credits to a User
// Add 100 credits to a user
const result = await creditService.addCreditsToUser(
userId,
100,
'Credit purchase',
'purchase',
);
Using Credits for a Service
// Use credits for OpenAI GPT-4 usage
const result = await creditService.useServiceCredits(
userId,
'openai.gpt-4',
5, // 5 units (e.g., 5000 tokens)
'Text generation with GPT-4',
);
Admin Panel
The admin panel provides the following functionality for managing the credit system:
- Service Cost Management: Add, edit, and delete service costs
- Credit Usage Analytics: View credit usage by service and user
- User Credit Management: Add credits to users and view credit balances
- Subscription Tier Configuration: Configure included credits for subscription tiers
Future Enhancements
- Credit Expiration: Implement credit expiration for time-limited credits
- Credit Bundles: Create bundles of credits with discounted pricing
- Service-Specific Credits: Implement credits that can only be used for specific services
- Usage Forecasting: Provide usage forecasting based on historical data
- Automated Cost Updates: Automatically update service costs based on third-party API pricing changes