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

# Billing & Credits

> A prepaid credit wallet you top up with Stripe, metered per voice minute and per chat message.

Flowyte runs on a **prepaid credit wallet**. You add funds, the platform meters usage as agents
work, and credits are drawn down in real time. \*\*1 credit = 1 cent ($0.01)**, so a $10 top-up is
1,000 credits.

## How metering works

Usage is metered per channel as it happens:

* **Voice** — per minute of connected call time.
* **Chat** — per message exchanged.
* **Toll-free inbound** — a call received on a toll-free (8XX) number bills your normal voice
  minute **plus a flat 2 credits/min** (\$0.02), the same on every plan. Toll-free is
  "called-party-pays," so the number owner covers the higher carrier cost. See the toll-free note
  below.
* **Call transfers** — per minute of the **forwarded** call, billed for the whole bridged duration
  including hold or queue time. Your AI charges stop at the hand-off, so forwarded minutes are a
  separate bucket from AI minutes.
* **Phone numbers** — a recurring monthly rental.

Each charge becomes a usage item with a `channel` (`voice` · `chat` · `transfer_minute` · `number`),
a `quantity` (the metered units), and the `credits` debited. Pull the day-by-day breakdown from
`GET /billing/usage/items`, or the rolled-up records from `GET /billing/usage`.

<Note>
  **Toll-free pass-through.** The flat 2-credit/min toll-free surcharge covers ordinary inbound
  traffic. In rare cases the underlying carrier charges more than that for a particular call — for
  example high-access or international originators, or the federal per-call payphone-origination fee —
  and those above-surcharge carrier costs are **passed through at cost**. Toll-free numbers may also
  be subject to inbound usage limits to protect against artificial traffic inflation.
</Note>

## Topping up with Stripe

`POST /billing/wallet/topup` starts a Stripe payment and returns a `clientSecret` your checkout UI
confirms. Once the payment settles, the credits land in the wallet. Downloadable invoices are
available from `GET /billing/invoices`.

<Note>
  `topup`, `auto-reload`, and changing your **plan** are completed through the dashboard session
  (Stripe checkout), not with an API key. Read endpoints — wallet, usage, plans, invoices — accept a
  key with `billing:read`.
</Note>

## Auto-reload

So an agent never goes silent mid-day, configure **auto-reload**: when the balance drops below
`thresholdUsd`, the platform charges `amountUsd` automatically.

```json theme={null}
PUT /billing/wallet/auto-reload
{ "enabled": true, "thresholdUsd": 20, "amountUsd": 50 }
```

## Plans

Plans (`Starter`, `Growth`, `Scale`) bundle included minutes at a lower per-minute rate plus an
overage rate beyond them; the wallet covers everything else. List them with `GET /billing/plans`
and read your current plan from `GET /billing/subscription`.

## In the API

| Action                             | Endpoint                             | Scope                              |
| ---------------------------------- | ------------------------------------ | ---------------------------------- |
| Get wallet balance                 | `GET /billing/wallet`                | `billing:read`                     |
| Top up via Stripe                  | `POST /billing/wallet/topup`         | dashboard session                  |
| Configure auto-reload              | `PUT /billing/wallet/auto-reload`    | dashboard session                  |
| Credit the wallet (manual / admin) | `POST /billing/wallet/credit`        | `billing:write`                    |
| List usage records                 | `GET /billing/usage`                 | `billing:read`                     |
| Itemized charges in a window       | `GET /billing/usage/items`           | `billing:read`                     |
| List plans                         | `GET /billing/plans`                 | `billing:read`                     |
| Get / change subscription          | `GET /billing/subscription` · `POST` | `billing:read` · dashboard session |
| List invoices (PDF links)          | `GET /billing/invoices`              | `billing:read`                     |

```bash theme={null}
# Check the balance before kicking off a batch of outbound work
curl https://builder.flowyte.com/api/v1/billing/wallet \
  -H "Authorization: Bearer flowyte_sk_…"
```

<Tip>
  Watch the balance from a server key with `billing:read` and alert your own ops channel — pair it
  with auto-reload so a spike in call volume never drains the wallet to zero.
</Tip>