---
title: AI credits
description: How AI credits work in Warmbly, what each AI action costs, the monthly allowance and reset rules, and how to buy top-up packs.
---

AI features run on credits. Your plan grants a monthly allowance that refreshes each billing cycle, and top-up packs never expire.

<Callout type="info" title="Who can manage credits">
Everything here lives on the **AI & credits** tab of **Settings > Billing** and needs the **Manage billing** permission. Other members do not see it.
</Callout>

## The two pools

| Pool | Refresh | Rollover |
|------|---------|----------|
| **Monthly allowance** | Reset to the plan amount each billing cycle | No, unused credits are replaced by the fresh grant |
| **Purchased credits** | Bought as top-up packs | Yes, they never expire and survive every reset |

Spending draws the monthly pool first and only touches purchased credits once it is empty, holding your top-ups in reserve for heavy months.

## What each action costs

Each action reserves a flat **minimum** up front (which also gates an empty balance before work starts), then settles against real token usage after the call.

| Action | Minimum |
|--------|---------|
| Writing assistant draft, selection edit ("Edit with AI") | 1 |
| AI assistant step | 1 per turn |
| Reply draft, compose draft, contact research run | 2 |
| Single-shot automation AI step (classify, extract, generate) | 1 |
| Automation AI agent step | 1 per step |
| AI switch or campaign switch step, AI decider (value decider is free) | 1 |
| Ask AI branch | 1 per evaluation |
| Per-recipient AI variable, instant / research mode | 1 / 2 per recipient |
| Web search by an AI step (only when results are found) | 1 |
| Inbox agent handled thread | 5 |

Five rules govern the settle:

- One credit buys a fixed token budget on the serving model: light models (mini and haiku class) at 1,500 tokens per credit, standard models at 400. The exact model and token count appear in the transaction log.
- **Overage can never fail a result you already received**; at worst it drains the balance to zero.
- A provider error refunds the reserved minimum automatically, so you are never charged for output you did not get.
- A contact research run that finds nothing still costs its credits. You are paying for the search, not the result.
- Running out returns "insufficient credits" **before** any work starts, so a depleted balance never leaves you half-charged.

## Usage and spend controls

The **AI usage & spend controls** card shows today, this week, and this month spend, a graph over the last 7, 30, or 90 days, and breakdowns by feature and model (credits, tokens, call counts). Each limit is set by slider or exact number and shows current spend against it; changes collect into a save bar.

| Control | Behavior |
|---------|----------|
| **Spend limits** | Optional hard caps per calendar day, ISO week, and calendar month. At the limit, AI pauses with a clear message until the window rolls over |
| **Per-member limits** | The same three windows per teammate, counting only charges they triggered. Workspace-level work (automations, inbox agent) is attributed to nobody |
| **Low-credit reminder** | Below your threshold, everyone with Manage billing gets an in-app alert, at most once a day |
| **Auto top-up** | Buys your chosen pack automatically when the balance dips below a threshold, bounded by a monthly purchase maximum. Needs the saved subscription card |

Who can use AI at all is separate: the **Use AI** role permission (see [Team and roles](/guides/team-roles/)).

## Allowances and top-ups

| Plan | Monthly credits |
|------|-----------------|
| Free trial | 50 (granted once, at trial start) |
| Starter | 250 |
| Pro | 2,000 |
| Enterprise | 25,000 |

Paid workspaces get a fresh grant each cycle, with the reset date shown beside your balance. Top-up packs come in **500**, **2,000**, and **10,000** credits, paid through Stripe Checkout with the card on file, landing in the purchased pool as soon as payment settles. Top-ups require an active paid plan.

<Callout type="warn" title="Purchases settle through Stripe">
Credits arrive only after Stripe confirms payment, not when you click. Closing the checkout tab charges nothing. A completed purchase is applied exactly once even if Stripe retries.
</Callout>

## The transaction log

Every grant, purchase, and spend, newest first, with the activity, model and token count, signed credit change, resulting balance, and time. Each spend records exactly what ran it: campaign, step, and contact for a switch step; automation, node, and run for an automation step (including what an Ask AI branch asked); the thread for inbox drafts; and the teammate behind manual features.

## FAQ

**Do unused monthly credits roll over?** No. Buy a top-up pack for credits that carry over.

**Do purchased credits expire?** No, through any number of resets.

**What happens when I change plans?** Your allowance follows the new plan from the next cycle. Purchased credits are unaffected.

**What happens if I cancel?** Monthly grants stop; any purchased balance stays until spent.

**Do credits apply when self-hosting?** Not when billing is off, which is the self-host default (`BILLING_PROVIDER=none`). You pay your AI provider directly, so the credit ledger is bypassed: nothing is debited, there is no plan allowance, the header shows no credit gauge, and per-action cost hints are hidden. A self-hosted install that runs Stripe (`BILLING_PROVIDER=stripe`) is metered exactly like the hosted product. Separately, a free or local model (`AI_PROVIDER=ollama`, or any provider with `AI_FREE=true`) is never charged and shows a "free model" notice. See the [self-hosting guide](/development/deployment-guide/).
