> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tesslate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing

> Credits, subscription tiers, app billing dimensions, and creator payouts in OpenSail

<img src="https://mintcdn.com/tesslate/VT6tbZolrCfpx26M/images/opensail-banner.png?fit=max&auto=format&n=VT6tbZolrCfpx26M&q=85&s=66579c47537b3464fb65b229cc9ab0fd" alt="Tesslate OpenSail" width="4712" height="1612" data-path="images/opensail-banner.png" />

## Overview

OpenSail uses a multi-source credit system for AI usage, a four-tier subscription model for platform access, and a per-app, per-dimension billing engine for published apps on the marketplace. Payments run through Stripe with idempotent webhook fulfillment.

<CardGroup cols={2}>
  <Card title="Four credit pools" icon="coins">
    Daily, bundled, signup bonus, and purchased, consumed in priority order
  </Card>

  <Card title="Four tiers" icon="layer-group">
    Free, Basic, Pro, Ultra, with increasing limits and BYOK on Pro+
  </Card>

  <Card title="Per-dimension app billing" icon="calculator">
    Three dimensions (AI, compute, platform fee), four modes per dimension
  </Card>

  <Card title="Creator payouts" icon="hand-holding-dollar">
    90% to creator, 10% platform, via Stripe Connect
  </Card>
</CardGroup>

## Credits

Credits are the unified currency for AI usage. One credit equals one US cent. Costs are calculated in cents with Decimal arithmetic so no rounding drift compounds over long runs.

### The four credit pools

| Pool             | Source                                        | Expiration                                | Priority             |
| ---------------- | --------------------------------------------- | ----------------------------------------- | -------------------- |
| **Daily**        | Free-tier allowance, 5 credits per day        | Resets at UTC midnight                    | 1st (consumed first) |
| **Bundled**      | Monthly allowance from your subscription tier | Resets every 30 days on your billing date | 2nd                  |
| **Signup bonus** | One-time gift at registration, 15,000 credits | Expires after 60 days                     | 3rd                  |
| **Purchased**    | Credit packages you buy                       | Never expire                              | 4th (consumed last)  |

Deduction priority is ordered to maximize the value of your purchased credits. Free pool gets used first, then bundled, then expiring bonus, then permanent purchased.

### How deduction works

<Steps>
  <Step title="Pre-request check">
    Before the agent calls the model, `check_credits(user, model_name)` verifies you have sufficient credits. BYOK routes always pass this check since no platform credits are charged.
  </Step>

  <Step title="Request runs">
    The model responds, token counts come back.
  </Step>

  <Step title="Cost calculation">
    `calculate_cost_cents(model, tokens_in, tokens_out)` looks up the current per-token prices (fetched live from LiteLLM, cached 5 minutes), multiplies, and rounds up with ceiling arithmetic. Non-zero usage always costs at least 1 cent.
  </Step>

  <Step title="Deduction">
    `deduct_credits` pulls from pools in priority order under a `SELECT FOR UPDATE` lock. Concurrent requests are serialized; the balance never goes negative.
  </Step>

  <Step title="Usage logged">
    A `UsageLog` row records model, tokens, cost, agent, project, and BYOK status.
  </Step>
</Steps>

### Credit packages

Buy credits that never expire:

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

Purchases complete through Stripe Checkout. Fulfillment is idempotent, so webhook replays don't double-credit.

## 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         | 0               | 0             | 0                |
| Max projects            | 3         | 7               | 15            | 40               |
| Max deployments         | 1         | 3               | 5             | 20               |
| BYOK                    | No        | No              | Yes           | Yes              |
| Support                 | Community | Email           | Priority      | Priority         |
| Annual billing          | N/A       | Available       | Available     | Available        |

<Info>
  Exact tier pricing and credit allocations are configured in the platform and can vary per deployment. Self-hosted instances can set their own tier structure.
</Info>

### Upgrading

<Steps>
  <Step title="Open Settings, Billing">
    The unified billing hub lives at Settings, Billing.
  </Step>

  <Step title="Pick a plan">
    Click Upgrade on the tier you want. Choose monthly or annual.
  </Step>

  <Step title="Stripe Checkout">
    You're redirected to Stripe's secure checkout. Card details never touch OpenSail servers.
  </Step>

  <Step title="Automatic activation">
    After payment succeeds, your tier updates, bundled credits are granted, the reset date is set 30 days out, and BYOK unlocks (if Pro or Ultra).
  </Step>
</Steps>

### Canceling

Cancellation takes effect at the end of the current period. You keep all tier benefits until then. Purchased credits are never affected by tier changes; they persist forever.

## Team billing

Teams have their own billing scope: a separate subscription tier, a separate credit balance, and a separate Stripe customer. Team admins manage billing at Settings, Team Billing. Individual team members use the team's credits when running agents on team-owned projects, and their personal credits for personal projects.

For teams with billing admins separate from platform admins, the permissions system (`orchestrator/app/permissions.py`) scopes billing actions to the admin role.

## App billing: three dimensions, four modes

Published apps on the Tesslate Apps marketplace have their own billing model, separate from platform credits. When a user installs your app, the creator decides who pays for what.

### The three dimensions

<Tabs>
  <Tab title="AI compute">
    All model calls the app's bundled agents make during execution. Priced per token, calculated through the same dynamic LiteLLM pricing used by the core credit system.
  </Tab>

  <Tab title="General compute">
    Non-AI runtime costs: container time, file operations, snapshot storage. Billed based on active runtime and persistent volume usage.
  </Tab>

  <Tab title="Platform fee">
    A percentage of total revenue that covers marketplace infrastructure, approval pipeline costs, and payout rails. Default is 10% (creators net 90%).
  </Tab>
</Tabs>

### The four modes per dimension

Each dimension can be set to one of four modes, independently:

| Mode                          | Who pays                                                          | When to use                            |
| ----------------------------- | ----------------------------------------------------------------- | -------------------------------------- |
| **Creator pays**              | The app creator pays this dimension                               | Free-to-try apps, lead-gen apps, demos |
| **Installer pays**            | The user installing pays this dimension                           | Standard marketplace apps              |
| **Platform subsidized**       | Tesslate covers this dimension                                    | Featured apps, promotional launches    |
| **BYOK (bring your own key)** | Installer uses their own provider key, bypassing routing entirely | Power users, enterprise installations  |

A creator might set AI compute to "installer pays", general compute to "creator pays" (absorbing hosting), and the platform fee to "installer pays". Or BYOK for AI compute so enterprise customers route through their own keys, while the creator still absorbs general compute.

### Promotional budgets

Creators can sponsor the first N installers by funding a promotional budget. While the fund lasts, all three dimensions are free to the installer. When the fund runs out, billing flips to whatever mode the creator configured.

This is the go-to pattern for launches: free for the first 1,000 installers, then installer-pays. Installers get a taste, creators get distribution.

### Caps and overage

Each dimension has its own caps and overage behavior configurable per app:

* Hard cap: stop executing when the cap is hit
* Soft cap: warn, prompt for an override, continue
* No cap: run until the subscriber's credits are exhausted

Caps protect both creators (from runaway installer usage when creator-pays) and installers (from runaway agents when installer-pays).

## Creator payouts

<Tabs>
  <Tab title="Revenue share">
    | Recipient | Share |
    | --------- | ----- |
    | Creator   | 90%   |
    | Platform  | 10%   |

    Revenue share applies to everything a creator sells: marketplace agents, published apps, paid skills, paid connectors. One-time purchases, subscriptions, and API-metered usage all split the same way.
  </Tab>

  <Tab title="Stripe Connect">
    Payouts go through Stripe Connect Express accounts. Creators onboard through a one-time Stripe flow (KYC, bank account, tax info). After onboarding, every sale that clears credits the creator's Stripe balance, which pays out to the creator's bank on Stripe's default schedule.
  </Tab>

  <Tab title="Payout visibility">
    Creators see earnings per app, per period, in Settings, Billing, Earnings. Stripe provides detailed transaction logs including payouts-in-flight.
  </Tab>
</Tabs>

## Usage tracking

<Steps>
  <Step title="Open billing">
    Settings, Billing.
  </Step>

  <Step title="Summary view">
    See total cost, tokens in/out, request count for the current billing period, broken down by model and by agent.
  </Step>

  <Step title="Detail view">
    Click into usage logs for per-request records with model, tokens, cost, agent, project, BYOK status, and timestamp.
  </Step>

  <Step title="Low-balance warning">
    At 20% of your monthly allowance remaining, the header shows a warning badge. At 0 credits, an out-of-credits modal prompts you to purchase or upgrade.
  </Step>
</Steps>

## Stripe reliability

OpenSail's Stripe integration is built for idempotency and reliability under webhook replay:

* Every fulfillment path checks the `stripe_payment_intent` for duplicate processing
* Verify-checkout on redirect is a safe no-op if the webhook already fulfilled
* Subscription updates, tier changes, and cancellations all log to the audit table
* Transfer and invoice creation include `idempotency_key` to prevent upstream replay

If a payment succeeds in Stripe but your credits don't update within 30 seconds, check Transaction History. Support can reconcile from the Stripe session ID.

## Test cards (for self-hosted and dev)

| Card                  | Behavior           |
| --------------------- | ------------------ |
| `4242 4242 4242 4242` | Succeeds           |
| `4000 0000 0000 0002` | Declined           |
| `4000 0025 0000 3155` | Requires 3D Secure |
| `4000 0000 0000 9995` | Insufficient funds |

Use these to test the full checkout flow locally.

## Troubleshooting

<AccordionGroup>
  <Accordion icon="credit-card" title="Payment declined">
    Card declined at the bank. Update payment method in Settings, Billing, or through the Stripe Customer Portal.
  </Accordion>

  <Accordion icon="circle-exclamation" title="Credits didn't post after purchase">
    Wait 30 seconds for the webhook to fire. Refresh the page (verify-checkout fallback). Check Transaction History for status. Contact support with the Stripe session ID if still missing.
  </Accordion>

  <Accordion icon="rotate" title="Bundled credits didn't reset">
    The daily reset loop runs hourly. Free-tier users reset at UTC midnight. Paid-tier users reset on their billing date; the Stripe webhook is the primary trigger, with a safety-net hourly sweep.
  </Accordion>

  <Accordion icon="chart-line" title="Credits depleting fast">
    Check usage by model in Settings, Billing, Usage. Switch heavy tasks to cheaper models (Haiku, Flash, Qwen-Coder). Add BYOK on Pro or Ultra to bypass credits entirely. Set per-run cost limits on specific agents.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Model Management" icon="microchip" href="/guides/model-management">
    Pick cost-effective models and understand BYOK
  </Card>

  <Card title="API Keys" icon="key" href="/guides/api-keys">
    Add BYOK provider keys and external API keys
  </Card>

  <Card title="Publishing Apps" icon="rocket" href="/guides/publishing-apps">
    Set up the three billing dimensions and promotional budgets
  </Card>

  <Card title="Marketplace" icon="store" href="/guides/marketplace">
    Browse apps and see pricing in the wild
  </Card>
</CardGroup>