Money

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.

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.

Each tool has its own price, and its page in the tools directory shows it. A tool is priced in one of five ways:

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 has the rules.

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.

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 -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"}'

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())

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());

{
  "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.

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.

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.

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.

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.

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.

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.