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

# Billing and credits

> One credit balance for every call, chat, and model request. Plans, per-minute pricing, top-ups, and what the API returns when the balance runs out.

Everything on Waterr is paid for from one **USD credit balance** per workspace: voice and video calls, text chat, model requests from the desktop app and the API, add-ons, and phone minutes. One credit is one US dollar.

There are no separate minute or token allowances to track. A call shows its price per minute before it starts, bills to the second while it runs, and stops cleanly when the balance reaches zero.

## Plans

| Plan | Monthly price | Annual price (per month) | Credits each month | Concurrent calls | Managed phone numbers |
| - | - | - | - | - | - |
| **Starter** | \$29 | $24 ($288 a year) | \$29 | 3 | 1 |
| **Growth** | \$99 | $82 ($984 a year) | \$99 | 10 | 5 |
| **Scale** | \$299 | $249 ($2,988 a year) | \$299 | 30 | 20 |
| **Enterprise** | Custom | Custom | Custom | Custom | Custom |

* **A plan's credits equal its monthly price.** On an annual plan you pay twelve discounted months up front, and you still get that month's credits every month.
* **Plan credits reset each month.** Credits you don't use in a period do not carry over to the next one.
* **Enterprise** adds SSO, white-label, and contract pricing. [Contact sales](mailto:harshit@waterr.ai?subject=Waterr%20Enterprise).

The plan catalogue is public, so a pricing page can read it without signing in:

```bash theme={null}
curl "https://waterr.ai/backend/api/billing/plans?currency=usd"
```

### The free trial

Every new workspace starts with a one-time **\$5 trial credit**, which is valid for 30 days. No card is needed. While you are on the trial:

* each call lasts at most **15 minutes**;
* only **one call** can run at a time;
* **outbound phone calls** are not available;
* models are limited to the **Gemini Flash family**.

Subscribing to any plan lifts these limits. Any trial credit you have left is still spent before your plan credits.

## Top-ups

Top-ups come in packs of **$10, $25, $50, or $100**, or any custom amount of **\$10 or more**.

* **Top-up credits roll over.** They never reset at the end of a period.
* **Spending order:** trial credit first, then this month's plan credits, then rolled-over credits and top-ups.
* **Overdraft:** a call that runs past zero can leave a small overdraft. It is capped at the larger of 5% of your plan and rolled-over credits or \$0.50, and your next top-up or renewal repays it first.

## What things cost

### Voice and video calls: per minute, billed to the second

A call's price per minute is the sum of the components it runs. Those are the voice model or speech-to-text, the LLM, and text-to-speech, plus a **\$0.05/min platform fee**, plus any add-ons you switch on. Typical stacks:

| Stack | Per minute |
| - | - |
| Gemini Live (the default realtime voice) | **≈ \$0.17** |
| Deepgram → Gemini 3.5 Flash → Cartesia Sonic | **≈ \$0.14** |
| Deepgram → Gemini 3.5 Flash → ElevenLabs Flash v2.5 | **≈ \$0.19** |
| Deepgram → Gemini 3.5 Flash → ElevenLabs Multilingual v2 | **≈ \$0.28** |

* **Bring your own keys and the component is free.** If a scenario uses your own vendor key for a component, that component costs \$0 on Waterr. You pay only the platform fee and any components Waterr hosts. The same applies to a [custom agent endpoint](https://docs.waterr.ai/api-reference/bring-your-own-agent.md) and to a phone number on your own carrier.
* **Failed calls are free.** You are refunded in full when a call fails on our side or a vendor's, or when the agent never speaks, as long as it billed for under 30 seconds.
* **Each extra human participant** beyond the first adds \$0.007/min.

### Add-ons, per minute while on

| Add-on | Per minute |
| - | - |
| Animated avatar | \$0.19 |
| Live vision | \$0.10 |
| Deep Think | $0.012 (during a turn: $0.037) |
| Recording | \$0.022 |
| Parallel transcript | \$0.012 |
| Deepfake detection | \$0.016 |
| Live slides | \$0.008 |
| Notepad | \$0.005 |

### Phone calls

Carrier minutes are added on top of the call's stack price. They cost from about **$0.009/min** (inbound) to **$0.022/min** (outbound), depending on the carrier and direction. A number on your own carrier costs \$0.

### Text chat, desktop app, and API model usage

These are billed **per token** at the model provider's list price × 1.6. A text chat therefore costs a little per message, depending on how long the message is. A typed session inside a meeting pays the \$0.05/min platform fee but none of the voice components, and its replies bill per message by tokens.

### The live rate card

Every price above comes from the public rate card, and that is the source of truth. It lists each component's `per_minute_sell` (per-minute items) or `unit_sell` (per-token and per-character items):

```bash theme={null}
curl https://waterr.ai/backend/pricing/rate-card
```

```json theme={null}
{
  "currency": "USD",
  "as_of": "2026-10-17T17:08:18.863Z",
  "components": [
    { "key": "infra.platform", "kind": "infra", "unit": "minute", "scope": "per_meeting", "per_minute_sell": 0.05, "unit_sell": 0.05, "status": "estimated" },
    { "key": "realtime.vertex.gemini-3.8-live", "kind": "realtime", "unit": "1m_in_tokens", "scope": "per_seat", "per_minute_sell": 0.120888, "unit_sell": 4.8, "status": "estimated" }
  ]
}
```

A `per_meeting` component is charged once per call. A `per_seat` component is charged once for each agent in the call.

### Quote an agent before you run it

To see what one of your agents will cost per minute, `POST /pricing/quote` with the agent's scenario id. It prices the exact stack a call would get, including bring-your-own-key components at \$0:

```bash theme={null}
curl -X POST https://waterr.ai/backend/pricing/quote \
  -H "Authorization: Bearer wai_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{"scenario_id": "<scenario-id>"}'
```

```json theme={null}
{
  "scenario_id": "<scenario-id>",
  "per_minute_total": 0.170888,
  "per_seat_total": 0.120888,
  "per_meeting_total": 0.05,
  "components": [
    { "key": "realtime.vertex.gemini-3.8-live", "kind": "realtime", "scope": "per_seat", "per_minute_sell": 0.120888, "byok": false },
    { "key": "infra.platform", "kind": "infra", "scope": "per_meeting", "per_minute_sell": 0.05, "byok": false }
  ],
  "conditional": []
}
```

`conditional` lists add-ons that bill only if they are used during the call, such as Deep Think during a turn.

## When the balance runs out

### Before a call: `402` and `429`

Creating a meeting is checked against your balance and your plan. You need at least one minute at the agent's price, and at least \$0.10 in any case. You also need a free concurrency slot.

Branch on the top-level `code`. The structured [`error`](https://docs.waterr.ai/api-reference/errors) object carries the generic class: `payment_required` for a 402 and `rate_limited` for a 429.

```json 402 insufficient_credits theme={null}
{
  "success": false,
  "code": "insufficient_credits",
  "message": "Not enough credits to start a call.",
  "remaining": 0.06,
  "per_minute": 0.170888,
  "minutes_left": 0,
  "required": 0.170888,
  "request_id": "req_…",
  "error": { "type": "invalid_request_error", "code": "payment_required", "message": "Not enough credits to start a call." }
}
```

```json 429 concurrency_limit theme={null}
{
  "success": false,
  "code": "concurrency_limit",
  "message": "This workspace already has 3 calls running (limit 3 on its plan).",
  "limit": 3,
  "live": 3,
  "request_id": "req_…",
  "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "This workspace already has 3 calls running (limit 3 on its plan)." }
}
```

```json 403 entitlement_required theme={null}
{
  "success": false,
  "code": "entitlement_required",
  "entitlement": "outbound_pstn",
  "message": "Outbound phone calls are not included in this plan."
}
```

* `per_minute` and `minutes_left` appear when the agent could be priced.
* On a 402, top up or upgrade, then retry the request unchanged.
* A 429 `concurrency_limit` is not a request-rate limit. Retrying with backoff only works once one of your calls ends.

### During a call: `credits_low` and `credits_exhausted`

A live call deducts from your balance as it runs. Two server messages reach the client over the call's RTVI channel:

**credits\_low** `server message`

Sent once, when about **90 seconds** of balance are left at this call's rate. Use it to prompt a top-up.

```json theme={null}
{ "type": "credits_low", "data": { "meeting_id": "…", "seconds_left": 85, "per_minute_total": 0.170888 } }
```

**meeting\_ended** `server message`

When the balance reaches zero, the agent says a short goodbye and the call ends with reason `credits_exhausted`. The usual post-call transcript, analysis, and [webhooks](https://docs.waterr.ai/api-reference/webhooks.md) still run.

```json theme={null}
{ "type": "meeting_ended", "data": { "reason": "credits_exhausted" } }
```

On the trial, a call also ends when it reaches its 15-minute cap.

## Billing endpoints

These are served at `https://waterr.ai/backend/api/billing`. `GET /plans` is public. Every other endpoint authenticates with a `wai_` API key or a signed-in session, and acts on that workspace's balance.

Prices are always decided by the server. You name a plan or a pack, and never send an amount. Payments go through Razorpay checkout. Each purchase endpoint returns what the checkout needs (`key_id` plus a `subscription_id` or `order_id`), and the matching `/confirm` call grants the credits. A confirm can be retried safely: a replay returns `alreadyProcessed: true`.

| Method | Path | What it does |
| - | - | - |
| `GET` | `/plans?currency=usd\|inr` | Public plan catalogue: `slug`, `name`, `price_monthly`, `price_annual_monthly`, `price_annual_total`, `monthly_credits`, `max_concurrent_calls`, `managed_numbers`, `api_limits`, `entitlements`, `contact_sales`. |
| `GET` | `/balance` | Your plan (`slug`, `interval`, `status`, `period_end`, `cancel_at_period_end`), `remaining`, `total`, the `buckets` (`trial`, `plan`, `rollover`, `overdraft`), and your `entitlements`. Never cached. |
| `POST` | `/subscribe` | `{ plan, interval: "monthly" \| "annual", currency }` → `{ subscription_id, short_url, key_id, checkout_session }`. |
| `POST` | `/subscription/confirm` | `{ razorpay_payment_id, razorpay_subscription_id, razorpay_signature }` → `{ granted, alreadyProcessed, balance }`. |
| `POST` | `/subscription/change` | `{ plan, interval }`. An upgrade takes effect now, and the unused credits from your old plan move to rollover. A downgrade takes effect at the end of the period. Returns `{ effective: "now" \| "period_end", short_url? }`. |
| `POST` | `/subscription/cancel` | Cancels at the end of the period → `{ cancel_at_period_end: true, period_end }`. You keep your plan until then. |
| `GET` | `/topup/packs?currency=` | `{ packs: [{ id, credits, price, currency }], custom_min: 10, custom_max }`. |
| `POST` | `/topup` | `{ pack_id }` or `{ custom_usd }`, plus `currency` → `{ order_id, amount, credits, currency, key_id, checkout_session }`. |
| `POST` | `/topup/confirm` | `{ razorpay_order_id, razorpay_payment_id, razorpay_signature }` → `{ granted, alreadyProcessed, credits, balance }`. Credits land in rollover. |
| `GET` | `/usage?from=&to=&group=service\|day` | Your spend over a range of up to 400 days. The default range is your current period. Returns `{ rows: [{ group, label, credits, quantity, unit }], total }`. With `group=service`, rows break down into voice minutes by stack, LLM, transcription, integrations, Agent Computer, avatar generation, phone numbers, and other. |

```bash theme={null}
curl https://waterr.ai/backend/api/billing/balance \
  -H "Authorization: Bearer wai_<your_key>"
```

Billing errors use the same `{ code, message }` shape. Common codes are `unsupported_currency`, `invalid_interval`, `unknown_pack`, `invalid_amount`, `no_subscription`, `no_change`, and `invalid_signature`.

> [!NOTE]
>
> The [request-rate limits](https://docs.waterr.ai/api-reference/rate-limits.md) on the REST API are not a billing control, and they are the same on every plan. Separately, each plan's `api_limits` (requests per minute, hour, and day) govern its model API traffic. Starter allows 60/1,000/10,000, Growth 200/5,000/50,000, and Scale 600/20,000/200,000.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.