Billing & Subscriptions - Tesslate Studio

Overview

Tesslate Studio uses a 4-tier subscription model with a multi-source credit system for AI usage billing. All payments are processed through Stripe with webhook-based fulfillment and idempotent processing to prevent duplicate charges.

4 Subscription Tiers

Free, Basic, Pro, and Ultra with increasing limits and features

Multi-Source Credits

Four credit pools (daily, bundled, signup bonus, purchased) consumed in priority order

Per-Token Pricing

Dynamic model pricing calculated in real time from provider rates

Stripe Powered

Secure checkout, webhook fulfillment, and customer portal via Stripe

Subscription Tiers

Feature	Free	Basic ($20/mo)	Pro ($49/mo)	Ultra ($149/mo)
Monthly Bundled Credits	0	500	2,000	8,000
Daily Credits	5/day	0	0	0
Max Projects	3	7	15	40
Max Deployments	1	3	5	20
BYOK (Bring Your Own Key)	No	No	Yes	Yes
Support	Community	Email	Priority	Priority
Annual Billing	N/A	Available	Available	Available

All paid tiers support annual billing at a discount. BYOK allows you to use your own AI provider API keys, bypassing platform credit costs entirely.

New users receive 15,000 bonus credits that expire after 60 days. These are tracked separately and consumed after daily and bundled credits but before purchased credits.

Credit System

Credits are the unified currency for AI usage in Tesslate Studio. 1 credit = $0.01 USD.

Credit Sources

Credits come from four sources, each with different characteristics:

Credit Type	Source	Expiration	Priority
Daily	Free-tier allowance (5/day)	Resets at UTC midnight	1st (consumed first)
Bundled	Subscription monthly allowance	Resets on billing date (every 30 days)	2nd
Signup Bonus	Registration gift (15,000 credits)	Expires after 60 days	3rd
Purchased	Credit packages bought separately	Never expires	4th (consumed last)

Credit Deduction Flow

When you use an AI model, credits are deducted in this exact order to maximize the value of your purchased credits:

Pre-Request Check

The check_credits(user, model_name) function verifies you have sufficient credits (or a BYOK key) before the AI request proceeds. BYOK models always pass this check.

AI Request Executes

The request is processed through the LiteLLM gateway, and the model generates a response.

Cost Calculation

calculate_cost_cents(model, tokens_in, tokens_out) computes the cost using dynamic pricing data. The formula uses Decimal arithmetic for financial precision:

cost = ceil(tokens_in/1M * input_price * 100) + ceil(tokens_out/1M * output_price * 100)

Credit Deduction

Credits are deducted in priority order: daily, then bundled, then signup bonus, then purchased. The deduction uses SELECT FOR UPDATE to lock the user row and prevent race conditions from concurrent requests.

Usage Logging

A UsageLog entry is created with model, tokens, cost, agent ID, and project ID. BYOK requests log with is_byok=True and billed_status="exempt".

Credit Packages

Purchase additional credits that never expire:

Package	Credits	Price
Small	500	$5
Medium	2,500	$25
Large	10,000	$100
Team	50,000	$500

The credit-to-cents ratio is 1:1. Purchasing 500 credits for

5 gives you

5 worth of AI usage.

Managing Your Subscription

Viewing Current Plan

Open Billing Settings

Click your profile icon, then Settings > Billing

View Plan Details

Your billing page shows:

Current tier and price
Bundled credits remaining vs. monthly allowance
Purchased credits balance
Total credits available
Credits reset date
Active subscription status

Upgrading Your Plan

Open Billing Settings

Navigate to Settings > Billing

Select a Plan

Click Upgrade on the desired tier (Basic, Pro, or Ultra)

Choose Billing Interval

Select monthly or annual billing

Complete Stripe Checkout

You are redirected to Stripe’s secure checkout page to enter payment details. Card information never touches Tesslate’s servers.

Automatic Activation

After payment, your tier upgrades immediately:

Subscription tier updates in your account
Bundled credits are granted for the new tier
Credits reset date is set to 30 days from now
BYOK access activates (Pro and Ultra)
Project and deployment limits increase

Canceling Your Subscription

Open Billing Settings

Navigate to Settings > Billing

Click Cancel

Click Cancel Subscription. By default, cancellation takes effect at the end of the current billing period.

Retain Access

You keep all tier benefits until the period ends. Your bundled credits remain available until they reset.

Downgrade

At the end of the period, your account downgrades to the Free tier:

Bundled credits reset to 0
Daily credits activate (5/day)
Purchased credits are NOT affected (they never expire)
Project and deployment limits reduce to Free tier levels

Renewing a Canceled Subscription

If you cancel but change your mind before the period ends, click Renew Subscription to remove the cancellation. Your subscription continues as normal.

Customer Portal

Click Manage Payment to access the Stripe Customer Portal where you can:

Update payment methods
View and download invoices
Manage billing details

Usage Tracking

Viewing Usage

The billing dashboard provides detailed AI usage analytics:

Summary View
Detailed Logs

Overview for the current billing period:

Total cost in cents and USD
Total input and output tokens
Total request count
Breakdown by model
Breakdown by agent

Low Balance Warnings

The credit status API monitors your balance and provides warnings:

Condition	Triggered When
`is_low`	Total credits fall to 20% or less of your monthly allowance
`is_empty`	Total credits reach 0

The frontend displays a warning indicator when your balance is low, prompting you to purchase additional credits or upgrade your tier.

Stripe Integration Details

Dual-Path Fulfillment

Tesslate uses a dual-path idempotent fulfillment pattern for maximum reliability:

Stripe Webhook: When Stripe sends a checkout.session.completed event, the backend fulfills the order
Verify Checkout: When the frontend redirects back from Stripe, it calls POST /api/billing/verify-checkout as a fallback

Whichever path fires first completes the fulfillment. The second path is a safe no-op, thanks to idempotency checks using the stripe_payment_intent as a unique key.

Webhook Events Handled

Event	Action
`checkout.session.completed`	Routes to subscription, credit, agent purchase, or deploy purchase handler
`customer.subscription.created`	Logged for audit
`customer.subscription.updated`	Logged for audit
`customer.subscription.deleted`	Downgrades user to Free tier or deactivates agent subscription
`invoice.payment_succeeded`	Marks usage logs as paid
`invoice.payment_failed`	Logged for follow-up

Security Measures

Measure	Description
Webhook Signature Verification	All Stripe webhooks verified using `STRIPE_WEBHOOK_SECRET`
Idempotent Fulfillment	`stripe_payment_intent` checked to prevent duplicate processing
Amount Cross-Validation	Credit purchases verify `session.amount_total` matches `metadata.amount_cents`
Session Ownership	Verify-checkout confirms `metadata.user_id` matches the authenticated user
PCI Compliance	Card details never touch the server; Stripe Checkout handles all payment input
Race Condition Safety	`IntegrityError` catch on commit handles webhook and verify-checkout races

Marketplace Purchases

Buying Agents

Purchase premium AI agents from the Marketplace:

Browse the Marketplace and find an agent
Click Purchase (one-time or monthly subscription)
Complete Stripe checkout
The agent is added to your Library immediately

Creator Payouts

If you sell agents on the Marketplace:

Split	Recipient
90%	Creator (via Stripe Connect)
10%	Platform fee

Creators receive payouts through Stripe Connect Express accounts. Revenue split is configurable via creator_revenue_share and platform_revenue_share in the platform config.

Billing API Reference

Subscription Endpoints

Endpoint	Method	Description
`/api/billing/subscription`	GET	Get current subscription status and limits
`/api/billing/subscribe`	POST	Create Stripe checkout for tier upgrade
`/api/billing/cancel`	POST	Cancel subscription at period end
`/api/billing/renew`	POST	Reactivate a canceled subscription
`/api/billing/portal`	GET	Get Stripe Customer Portal URL

Credit Endpoints

Endpoint	Method	Description
`/api/billing/credits`	GET	Get detailed credit balance
`/api/billing/credits/status`	GET	Get low balance warning status
`/api/billing/credits/purchase`	POST	Create Stripe checkout for credit package
`/api/billing/credits/history`	GET	Get credit purchase history

Usage Endpoints

Endpoint	Method	Description
`/api/billing/usage`	GET	Usage summary for a date range
`/api/billing/usage/logs`	GET	Detailed per-request usage logs
`/api/billing/usage/sync`	POST	Manually sync usage from LiteLLM

Other Endpoints

Endpoint	Method	Description
`/api/billing/transactions`	GET	Combined transaction history
`/api/billing/earnings`	GET	Creator earnings (for marketplace sellers)
`/api/billing/connect`	POST	Create Stripe Connect onboarding link
`/api/billing/config`	GET	Public billing configuration (no auth required)

Testing (Development)

Test Cards

Card Number	Result
`4242 4242 4242 4242`	Payment succeeds
`4000 0000 0000 0002`	Card declined
`4000 0025 0000 3155`	Requires authentication (3D Secure)
`4000 0000 0000 9995`	Insufficient funds

Local Webhook Testing

# Install Stripe CLI
brew install stripe/stripe-cli/stripe

# Login to Stripe
stripe login

# Forward webhooks to your local server
stripe listen --forward-to localhost:8000/api/billing/webhooks/stripe

# Copy the webhook signing secret to your .env
STRIPE_WEBHOOK_SECRET=whsec_...

Troubleshooting

Payment Failed

Common causes:

Insufficient funds
Card expired
Bank declined the transaction

Solution: Update your payment method in Settings > Billing or through the Stripe Customer Portal.

Credits Not Added After Purchase

Credits should be added immediately after payment. If not:

Refresh the page (the verify-checkout fallback may need to trigger)
Check Settings > Billing > Transaction History for the purchase status
Wait up to 30 seconds for the Stripe webhook to process
Contact support if the transaction shows as completed but credits are missing

Subscription Not Updating After Checkout

Possible causes:

Webhook endpoint is not accessible
Webhook secret mismatch
Database error during fulfillment

Solutions:

The frontend’s verify-checkout should handle this automatically on redirect
Check that STRIPE_WEBHOOK_SECRET matches the value in your Stripe dashboard
Contact support with your Stripe session ID for manual resolution

Credits Depleting Too Fast

Solutions:

Check your usage breakdown by model in Settings > Billing > Usage
Switch to less expensive models for simple tasks (GPT-3.5, Claude Haiku)
Add your own API keys (BYOK) on Pro or Ultra tiers to bypass credit costs
Set per-run cost limits on your agents to prevent runaway usage
Purchase a larger credit package for better value

Low Balance Warning Not Showing

Check:

The threshold is set to 20% of your monthly allowance
Verify the GET /api/billing/credits/status endpoint returns is_low: true
Refresh the page to re-fetch credit status

Next Steps

Model Management

Understand AI model pricing and choose cost-effective models

API Keys

Set up BYOK to use your own AI provider keys

Marketplace

Browse and purchase premium agents

External Deployments

Deploy projects and manage deployment slots

Get Started

Self-Hosting

Core Concepts

Working with Projects

AI Agents

Advanced Features

Developer Guide

Development

​Overview

4 Subscription Tiers

Multi-Source Credits

Per-Token Pricing

Stripe Powered

​Subscription Tiers

​Signup Bonus

​Credit System

​Credit Sources

​Credit Deduction Flow

​Credit Packages

​Managing Your Subscription

​Viewing Current Plan

​Upgrading Your Plan

​Canceling Your Subscription

​Renewing a Canceled Subscription

​Customer Portal

​Usage Tracking

​Viewing Usage

​Low Balance Warnings

​Stripe Integration Details

​Dual-Path Fulfillment

​Webhook Events Handled

​Security Measures

​Marketplace Purchases

​Buying Agents

​Creator Payouts

​Billing API Reference

​Subscription Endpoints

​Credit Endpoints

​Usage Endpoints

​Other Endpoints

​Testing (Development)

​Test Cards

​Local Webhook Testing

​Troubleshooting

​Next Steps

Model Management

API Keys

Marketplace

External Deployments

Overview

Subscription Tiers

Signup Bonus

Credit System

Credit Sources

Credit Deduction Flow

Credit Packages

Managing Your Subscription

Viewing Current Plan

Upgrading Your Plan

Canceling Your Subscription

Renewing a Canceled Subscription

Customer Portal

Usage Tracking

Viewing Usage

Low Balance Warnings

Stripe Integration Details

Dual-Path Fulfillment

Webhook Events Handled

Security Measures

Marketplace Purchases

Buying Agents

Creator Payouts

Billing API Reference

Subscription Endpoints

Credit Endpoints

Usage Endpoints

Other Endpoints

Testing (Development)

Test Cards

Local Webhook Testing

Troubleshooting

Next Steps