# Billing and credits

> Prepaid credits per account, how usage draws them down, adding credits by card, auto-recharge, and what happens at zero.

Accounts are **prepaid**. Credits come in by card, and every billable unit (an AI call, an action, an email, a database day, a live company filing) is drawn from them at the price on its usage line, the moment it is recorded. A new account starts with **$2 of trial credit**.

## Your balance

```bash
vibiz billing                       # balance, status, card, auto-recharge, recent history
vibiz billing top-up 25             # a payment link for $25 (a person opens it and pays)
vibiz billing history --kind usage  # what used the money, one line per day
vibiz billing auto-recharge on --threshold 5 --amount 25   # full-access key
```

```bash
curl https://thelastapi.dev/v1/billing -H "Authorization: Bearer $VIBIZ_API_KEY"
```

```json
{
  "object": "billing",
  "mode": "credits",
  "balance_cents": 1834,
  "status": "active",
  "card": { "brand": "visa", "last4": "4242", "exp_month": 12, "exp_year": 2030 },
  "auto_recharge": { "enabled": true, "threshold_cents": 500, "amount_cents": 2500, "failures": 0, "disabled_reason": null },
  "daily_spend_limit_usd": 5,
  "agent_domain_limit_cents": null,
  "agent_email_limit_per_month": null,
  "next_step": null,
  "console_url": "https://thelastapi.dev/billing"
}
```

| `status` | Means |
| --- | --- |
| `active` | Paid calls run |
| `low` | Below $1: the console shows a banner, the owner gets one email |
| `payment_required` | At or below $0: paid calls answer `402 payment_required` |
| `past_due` | At or below $0 for 7 days: deploys, new projects and new resources pause too |
| `exempt` | thelastapi covers this account's usage |

What is running keeps running at any balance: sites, databases, sign-in and analytics are never stopped or deleted for money. Free things keep working too: your own AI provider key, connector calls, reads, the console, and adding credits.

**Credits held for a broadcast.** When a broadcast is sent or scheduled, its cost (recipients × $0.001) is held: the balance other calls can spend is lower by what it hasn't sent yet, and each batch is charged as it goes out (an `email.marketing` line in usage). Canceling releases what wasn't sent. **Agents and marketing email**: `agent_email_limit_per_month` (owner, `PATCH /v1/billing`, `null` turns it off) lets agents send broadcasts and run automations up to that many emails a month without the owner pressing Send ([Email](https://thelastapi.dev/docs/email#what-agents-can-do-with-contacts-and-broadcasts)).

## Adding credits

In the console: **Add credits** on Billing, on Usage, or from the balance in the sidebar ($10, $25, $50, $100 or any amount from $5 to $1,000). You pay on a hosted card page; receipts come by email. The card is saved for auto-recharge unless you untick it. `POST /v1/billing/checkout {"amount_cents": 2500}` returns the same page's `url`.

**Auto-recharge** charges the saved card when the balance falls below a threshold (at least $5), for an amount you choose ($10–$1,000). If the card is declined you get an email and it tries again an hour later; after two declines in a row it turns itself off.

Whenever credits arrive (a top-up, an auto-recharge, or credits support adds), the account's owners get one email: how much, how it came in, and the new balance.

## The daily safety cap

Separate from the balance, each account has a daily cap on AI and actions (default $5 per UTC day). It stops a looping agent from spending the whole balance in one go. An owner raises it in **Billing** or with `PATCH /v1/billing {"daily_spend_limit_usd": 50}` (up to $1,000). Past it: `429 rate_limited`, `details.reason: "daily_spend"`, with `raise_url` (Billing, the field focused).

## Limit alerts

The account's owners get one email when a cap reaches 80 % and one when it is hit or refuses a request: the daily safety cap, each project's AI budget, the plan's projects, builds, app email, agents' monthly email, texts and calls. Each says which cap and project, usage against the limit, what stops and when it resets, and links to the setting that raises it (`/billing?edit=daily_spend_limit`, `/projects/:id/ai?edit=ai_budget`…). Overview and Usage show the same banner while a cap is at 80 % or more. Turn a kind of email off in **Billing ▸ Limit alerts** (`PATCH /v1/billing {"limit_alerts": {"daily_spend": false}}`); `GET /v1/billing` → `limit_alerts` lists them. See [Usage ▸ Limits](https://thelastapi.dev/docs/usage#limits) for every cap.

## When credits run out

```json
{ "error": { "code": "payment_required", "message": "This account is out of credits. Add credits to keep using paid calls.",
  "details": { "reason": "insufficient_balance", "balance_cents": 0,
    "next_step": "Tell the user: add credits in the console ▸ Billing (or turn on auto-recharge). Retrying will not work until then.",
    "console_url": "https://thelastapi.dev/billing", "top_up_url": "https://thelastapi.dev/billing?top_up=1" } } }
```

A call is also refused when its worst case (an AI call's `max_tokens` at list price) could take the balance more than $0.50 below zero. Lower `max_tokens` or add credits.

## A live company filing

A production filing is paid before it is filed: from the balance (`POST …/company/submit` answers `402` when the credits fall short of the quote), or by card with `POST /v1/projects/:id/company/checkout?env=production` (the same body as submit), which files it the moment the payment arrives. A filing the partner refuses is refunded: to the balance, or to the card it was paid with.

## What agents can and can't do

Agents read the balance (`vibiz_billing`, `vibiz_usage` shows `limits.credits`) and can make a payment link for a person (`vibiz_billing` `top_up`); they never take card data. Changing auto-recharge, the cap or the card is an owner's.
