---
title: "The balance, prices, top-ups and refunds"
url: "https://conecto.chat/docs/money"
markdown: "https://conecto.chat/docs/money.md"
description: "How an agent pays on Conecto: one prepaid balance in US dollars, a price for each call, free reads and downloads, top-ups, auto-reload and refunds."
section: "Concepts"
published: 2026-10-19
updated: 2026-10-27
---

# Money

An account has one prepaid balance in US dollars. Each call is paid from it at the tool's own price, and a call that fails costs nothing.

## The balance

`GET /v1/balance`, or the `account_balance` tool, shows the balance with the key's daily budget, the account's monthly ceiling, auto-reload and the month's free reads and downloads. Checking it never counts as a read.

| Field | What it is |
| --- | --- |
| `balance_usd` | What the account can spend now: its credit, less what running calls hold, plus the reload amount while auto-reload is on. |
| `reserved_usd` | What running calls hold until they settle. |
| `daily_budget_usd` | This key's daily budget. |
| `monthly_ceiling_usd` | The account's monthly ceiling. |
| `auto_reload` | Whether auto-reload is on, and its amount. |
| `free_this_month` | The month's free reads and downloads: what is used, what was bought and when they start again. |

When the balance is empty, the reply also says how to top up, the smallest top-up, the fee and the first top-up's offer.

Every amount is a string in US dollars with as many decimals as it needs, at least two. Prices go down to a millionth of a dollar, like `$0.0005` for some calls.

## Prices

Each tool has its own price, and its page in the [tools directory](https://conecto.chat/tools.md) shows it. A tool is priced in one of five ways:

| Model | Tools | How it is charged | For example |
| --- | --- | --- | --- |
| Free | 313 | Costs nothing. A read counts toward the month's free reads. | [`crm_search`](https://conecto.chat/tools/crm/crm_search.md): free up to the month's 1,000,000 reads |
| Per call | 219 | One price for each call that succeeds. | [`crm_save_contact`](https://conecto.chat/tools/crm/crm_save_contact.md): $0.01 |
| Per item | 40 | A price for each thing the call handles, like each record saved or each page read. The most it can cost is held first. | [`crm_save_contacts`](https://conecto.chat/tools/crm/crm_save_contacts.md): $0.01 per record saved |
| Metered | 8 | What the work cost, known once it is done, up to a stated most. AI work is charged at the model's cost plus 40% unless the tool says otherwise. | [`email_send`](https://conecto.chat/tools/email/email_send.md): $0.001 per recipient, plus $0.001 per started MB of attachments for each recipient ($0.001 to one person without attachments), up to $0.52 |
| Quoted | 1 | The price in a quote the tool gives first, up to a stated most. | [`phone_rent_number`](https://conecto.chat/tools/phone/phone_rent_number.md): quoted, up to $25.00 |

A change to a record, like saving a contact, costs $0.01. Monthly rentals, like an inbox at $1.00 a month, renew from the balance, and [Rentals](https://conecto.chat/docs/money.md#rentals) has the rules.

## Free each month

Every account gets these each calendar month, in UTC:

- **1,000,000 reads.** A read is a call to a free tool that only reads, over REST, MCP or a schedule. Past that, the read that needs more buys 10,000 more for $0.50 before it runs, and its reply says so in `bought`.
- **5 GB of downloads** through the account's download links. Past that, the download that needs more buys 1 GB for $0.30. The first 5 downloads of each copy of the account's own data are free.

A block bought this way shows in the call log as a call of its own, and it lasts until the month ends. When the balance or a budget is short for the next block, the read is refused like a paid call and stays uncounted. These never count, since they show where the account stands, help fix it or answer a person's data request: `account_balance`, `account_find_person`, `account_get_call`, `account_get_limits`, `account_list_calls` and `account_owner_link`.

`free_this_month` in the balance shows where the month stands, and its `resets_at` says when it starts again.

## Top-ups

`POST /v1/topups` with `amount_usd` answers with a Stripe checkout link to pay once. Open it, or hand it to the owner. The credit lands within seconds of the payment.

- A top-up is $5 to $5,000, in whole cents.
- The fee is 7% + $0.35 a top-up: Stripe's fees, passed on.
- The account's first top-up is doubled, up to $20 extra.
- Stripe takes the payment as the merchant of record and sends the receipt and the invoice.

curl:

```bash
curl -X POST https://api.conecto.chat/v1/topups \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": 20, "po_number": "4500012345"}'
```

Python:

```python
import os
import requests

reply = requests.post(
    "https://api.conecto.chat/v1/topups",
    headers={"Authorization": f"Bearer {os.environ['CONECTO_KEY']}"},
    json={
        "amount_usd": 20,
        "po_number": "4500012345",
    },
)
print(reply.status_code, reply.json())
```

JavaScript:

```javascript
const reply = await fetch("https://api.conecto.chat/v1/topups", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CONECTO_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount_usd: 20,
    po_number: "4500012345",
  }),
});
console.log(reply.status, await reply.json());
```

```json
{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_a1B2c3D4e5F6g7H8",
  "amount_usd": "$20.00",
  "fee_usd": "$1.75",
  "total_usd": "$21.75",
  "first_topup_bonus_usd": "$20.00",
  "credited_usd": "$40.00",
  "how": "Open the link, or hand it to your owner. Credit lands within seconds of payment.",
  "po_number": "4500012345"
}
```

`GET /v1/topups` lists the credit added, newest first: top-ups, bonuses, auto-reloads and free credit, up to the last 100.

### Buying for a company

Add `po_number` with a purchase order number, and it is printed on the receipt and the invoice. At checkout, enter the company's name, and "I'm providing a tax ID" appears for its VAT ID.

## Auto-reload

`POST /v1/auto-reload` with `amount_usd` turns on auto-reload with one Stripe checkout. After that, once the prepaid credit is used, calls can run up to the reload amount past zero. Stripe charges the saved card each time that usage reaches the amount, plus the 7% + $0.35 fee, and the paid invoice refills the balance.

- `GET /v1/auto-reload` shows its status: `off`, `pending` until the first payment, `active`, or `failed` when a card payment failed.
- `POST` again while it is on changes the amount.
- `DELETE /v1/auto-reload` turns it off, and a last invoice bills the usage left.
- A scoped key turns it neither on nor off, and answers `key_scope`.

The reload amount keeps the bounds of a top-up: $5 to $5,000.

## Refunds

`account_refund_topup` refunds a top-up paid in the last 24 hours, while none of it is used. Its credit and the first top-up's bonus leave the balance, the card gets the credit's share back with its tax, and the service fee is kept. The owner can refund on the account page too. In `GET /v1/topups`, `refundable_until` says how long each top-up stays refundable. An auto-reload pays for calls already made, so only a top-up is refunded.

## Free credit

A new account gets $1 of free credit, for one new account per network a day. Free credit pays for work inside the business. Email, calls and documents sent to people outside it need one real top-up, or auto-reload, first. Until then they answer `payment_required_for_outbound`.

AI visibility and the phone (calls, their minutes and a phone number's rent) run only on credit bought with a top-up. Free credit, from signup, a beta invitation or a first top-up's bonus, goes to every other tool, which spends it first. When the credit bought is too little for one of these calls, it answers `purchased_credit_required`. `account_balance` shows both parts: `bought_credit_usd` and `free_and_bonus_credit_usd`.

## Rentals

Some things are rented by the month: inboxes, phone numbers, extra storage, uptime monitors, schedules, analytics sites, websites, the people kept in HR and a public help center. The call that rents one pays the first month. After that it renews from the balance on the same day each month. When the balance is short, the rental gets 7 days' grace, tried again each day, and is then released.

## When the balance runs low

With auto-reload off, the bot gets the event `account.balance_low` when the balance falls to a fifth of what the last top-up left, and `account.balance_empty` when it runs out. The owner gets an email each time, once per top-up. Paid tools then answer `insufficient_balance` with status 402 until someone adds credit. A caller to the business's phone line can still leave a message, for free, and it arrives as `phone.message_left`.

## More in the docs

- Previous: [Events and webhooks](https://conecto.chat/docs/events.md)
- Next: [Limits](https://conecto.chat/docs/limits.md)
- Every page in one file: https://conecto.chat/docs/all.md
- Every page's title and address: https://conecto.chat/docs/index.json