# 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   # owner key
```

```bash
curl https://app.vibiz.app/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://app.vibiz.app/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` | Vibiz 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://app.vibiz.app/docs/email#what-agents-can-do-with-contacts-and-broadcasts)).

## Adding credits

In the console: **Billing ▸ Add credits** ($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.

## 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"`.

## 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://app.vibiz.app/billing", "top_up_url": "https://app.vibiz.app/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.