> ## Documentation Index > Fetch the complete documentation index at: https://docs.teamfollowup.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use the public API base URL: https://api.teamfollowup.ai/api. > Authenticate public API requests with Authorization: Bearer YOUR_API_KEY. > Use product-owned terms: agents, campaigns, projects (GoHighLevel sub-accounts), contacts, calls, outcomes, skills, cadences, phone numbers. > Scope requests by locationId rather than projectName. > Read the guide linked from each API reference group before recommending an endpoint. # Balances, spend and sub-account wallets > How your agency wallet, your spend and your sub-accounts' wallets fit together, and what every figure the billing endpoints return means. The billing endpoints answer "where do we stand?" without you stitching a picture together from a dozen calls. Start with the summary. Reach for the lists only when you need the detail behind a number. Every billing read covers your own agency: the one your API key belongs to. There is no parameter that selects another. ## Where you stand `GET /api/billing/summary` returns one object with these sections. | Section | What it tells you | | ----------------- | -------------------------------------------------------------------------------------------------------- | | `balance` | Minutes and dollars left in your wallet, any debt, the rate your next minute is drawn at, and your plan. | | `autoRecharge` | Whether auto-recharge can actually charge, not just whether it is switched on. | | `subscription` | Your platform subscription: status, renewal, and any problem to act on. | | `pendingPurchase` | A plan purchase in progress, or `null` when there is none. | | `spendThisMonth` | What this calendar month has cost so far. | | `subAccounts` | How many sub-accounts you have, how many rebill, and which rebilled ones are running low. | | `pendingCredits` | Sub-account payments waiting for wallet credit. | Each section loads on its own. When one cannot be loaded it comes back `null` and its name appears in `unavailable`. So a `null` section named in `unavailable` means "unknown right now", and any other `null` means "none". `attention` lists what needs a person, most urgent first. Each item has a `code`, a `severity` (`ACTION_REQUIRED`, `WARNING` or `INFO`) and a `message` you can show as it is. | `code` | Raised when | | ------------------------------- | ---------------------------------------------------------------------------------- | | `BALANCE_EMPTY` | Your wallet has no minutes left. | | `BALANCE_LOW` | Your wallet is running low. | | `IN_DEBT` | Your wallet owes minutes. Your next purchase settles them first. | | `AUTO_RECHARGE_ACTION_REQUIRED` | Auto-recharge cannot charge your card until someone acts. | | `SUBSCRIPTION_ACTION_REQUIRED` | Your platform subscription needs attention. | | `PURCHASE_PENDING` | A plan purchase is in progress. | | `PURCHASE_NEEDS_SUPPORT` | Our support team is reconciling a purchase. Do not pay again. | | `SUB_ACCOUNTS_LOW` | One or more rebilled sub-accounts are low or empty. | | `PENDING_CREDITS` | A sub-account has paid, and its minutes are added once your wallet can cover them. | An agency exempt from payment is never told its wallet is low. ## The transaction history `GET /api/billing/transactions` is one paged list of everything that moved your agency wallet in a window, newest first. | `type` | What happened | `walletEffect` | `cashFlow` | | -------------------- | -------------------------------------------------------------------------- | -------------- | ------------- | | `PURCHASE` | You bought minutes. | `ADD` | `PAID_BY_YOU` | | `BONUS` | Minutes were gifted to you. | `ADD` | `NONE` | | `SUB_ACCOUNT_TOP_UP` | A sub-account paid you, and the minutes it bought came out of your wallet. | `DEDUCT` | `PAID_TO_YOU` | | `MINUTES_RETURNED` | A sub-account's unused minutes came back to you. | `ADD` | `NONE` | | `CALL_USAGE` | Calls your wallet paid for, one row per sub-account per day. | `DEDUCT` | `NONE` | | `PHONE_NUMBER` | A phone number was bought or renewed. | `DEDUCT` | `NONE` | | `CO_AUTHOR` | Co-author usage for a day was settled. | `DEDUCT` | `NONE` | `walletEffect` is what the row did to your wallet. `cashFlow` is whether money changed hands. For `SUB_ACCOUNT_TOP_UP`, `amountUSD` is what the sub-account paid you. `CALL_USAGE` counts only calls your wallet paid for: calls from sub-accounts that do not rebill, calls you covered when a rebilled sub-account had no card, and the part of a call that ran past a sub-account's minutes. A call a sub-account paid for from its own minutes is not a second charge to you, so it is not on this list. It is in the usage figures below. Filter with `type` and `locationId`. Filtering by sub-account leaves out agency-level rows such as your own purchases. ## Usage and cost `GET /api/billing/usage` totals a window and breaks it down by `sub_account` (the default) or by `day`. | Field | Meaning | | -------------------- | ---------------------------------------------------------------------------- | | `callCostUSD` | What the calls cost you at your platform rate, whichever wallet funded them. | | `billedToClientsUSD` | What rebilled sub-accounts were charged for the same calls. | | `phoneNumbersUSD` | Phone number purchases and renewals. | | `coAuthorUSD` | Co-author usage settled into your wallet. | | `totalCostUSD` | `callCostUSD` plus `phoneNumbersUSD` plus `coAuthorUSD`. | `callCostUSD` and `billedToClientsUSD` describe the calls, so they lag the money: a sub-account that bought minutes it has not used yet has paid you for them already. Phone numbers and co-author usage belong to your agency, so they appear in `totals` and in each `day`, never under a sub-account. ## Sub-account wallets `GET /api/billing/sub-accounts` lists every connected sub-account. A disconnected one is not listed. * `rebilling`: whether the sub-account pays for its own calls from its own wallet, and the `clientRatePerMinute` you charge it. * `wallet`: `balanceMinutes` (bonus minutes included, expired batches not), `balanceUSD`, `debtMinutes`, and whether the sub-account can see its wallet (`visibility`, `ENABLED` or `DISABLED`). * `autoRecharge`: set in dollars. `thresholdUSD` is the dollar balance it tops up below, and `rechargeAmountUSD` is what each top-up charges. * `creditGuard`: whether the sub-account stops its own calls when its wallet is empty. * `pendingCredits`: payments the sub-account has made that are waiting for credit in your wallet. The wallet `status` is `ACTIVE`, `LOW_BALANCE`, `IN_DEBT` or `DEPLETED`. A sub-account that does not rebill is funded by your wallet, so an empty balance there is normal. The summary only flags rebilled ones. `GET /api/billing/sub-accounts/{locationId}` adds the `creditBatches` behind the balance, oldest first, which is the order they are drawn down. ## Invoices and receipts `GET /api/billing/documents` lists proof of payment. * `scope=platform` (the default): what your agency paid the platform. An `INVOICE` for your subscription, a `RECEIPT` for each wallet top-up. * `scope=sub_accounts`: what your sub-accounts paid you. Always a `RECEIPT`. Narrow with `type` (`ALL`, `INVOICE` or `RECEIPT`). The platform list is built from two sources and capped. When `truncated` is `true`, it is not complete history. ## Changing billing The same module changes billing. Two scopes split it by what a call does to money: * `billing:write` changes settings. Nothing is charged when the call returns, though switching auto-recharge on permits charges later. * `billing:charge` charges a card when the call returns. `billing:write` does not include it, every such operation needs an `Idempotency-Key`, and none of them is available to an assistant over MCP. For your agency: | Operation | What it does | | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Update agency auto-recharge](/api-reference/billing/update-agency-auto-recharge) | Switches auto-recharge on or off and picks the plan it buys: `SILVER`, `GOLD` or `DIAMOND`. | | [Buy a plan](/api-reference/billing/buy-a-plan) | A self-serve agency is charged now and gets `PAID`, or `PROCESSING` while Stripe finishes. A managed agency gets `PENDING_APPROVAL`: our team approves and charges it. | For a sub-account, every change needs your plan to include rebilling and Stripe Connect to be connected, even a change that turns something off: | Operation | What it does | | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [Update sub-account rebilling](/api-reference/billing/update-sub-account-rebilling) | On sets the client rate and links the Stripe customer, all or nothing. Off returns the sub-account's unused minutes to your wallet at what they cost you, switches its auto-recharge off and unlinks its Stripe customer. Minutes the client paid for become your credit; nothing is refunded to the client. | | [Enable rebilling with a charge](/api-reference/billing/enable-rebilling-with-a-charge) | The same on, plus a first charge to the client's card. | | [Charge a sub-account](/api-reference/billing/charge-a-sub-account) | Tops up the wallet from the client's card. The charge answers `SUCCEEDED`, or `CREDIT_PENDING` if the card was charged and the minutes have not landed yet. Retrying with the same `Idempotency-Key` replays that answer and charges nothing. | | [Update sub-account auto-recharge](/api-reference/billing/update-sub-account-auto-recharge) | Tops the wallet up automatically, in dollars. | | [Update sub-account Credit Guard](/api-reference/billing/update-sub-account-credit-guard) | Stops the sub-account's calls when its wallet is empty. [Several at once](/api-reference/billing/update-credit-guard-for-sub-accounts). | | [Link a Stripe customer](/api-reference/billing/link-a-stripe-customer) | Links one customer to the sub-accounts you name, all or nothing. Needs an `Idempotency-Key`, because the sub-accounts are linked one at a time. | | [Unlink a Stripe customer](/api-reference/billing/unlink-a-stripe-customer) | Unlinks it. Nothing is deleted in Stripe. | The walkthrough is [Set up rebilling for a sub-account](/billing/set-up-rebilling). ## Windows `dateFromUTC` and `dateToUTC` select whole UTC days. A timestamp selects the day it falls on. Leave both out and the history and usage endpoints read the last 30 days. A window can cover at most 366 days. Documents are not windowed unless you ask. See [Conventions](/conventions#dates-and-times). ## Boundaries * Adding cards, creating Stripe customers and connecting Stripe stay in the dashboard. The API never takes card details. * Anything that charges a card needs the `billing:charge` scope and an `Idempotency-Key`, and is not available over MCP. * Only an agency admin's credential can change billing. Reads also admit a staff credential carrying an agency of its own. A sub-account user gets `403` either way, because every figure here is agency-wide. * A key needs the `billing:read` scope to read. `billing:write` covers it. `billing:charge` covers neither. * A sub-account belongs to the agency that owns it. One that is only shared with you is not in your billing. * A `locationId` that is not one of your connected sub-accounts returns `404`, whether it does not exist or belongs to someone else. ## In the API * [Get billing summary](/api-reference/billing/get-billing-summary) * [List billing transactions](/api-reference/billing/list-billing-transactions) * [Get billing usage](/api-reference/billing/get-billing-usage) * [List billing documents](/api-reference/billing/list-billing-documents) * [List sub-account wallets](/api-reference/billing/list-sub-account-wallets) * [Get sub-account wallet](/api-reference/billing/get-sub-account-wallet) * [Update sub-account rebilling](/api-reference/billing/update-sub-account-rebilling) * [Charge a sub-account](/api-reference/billing/charge-a-sub-account) * Every field, one line each: [Glossary](/glossary#billing) ## Related * [Agencies, projects and sub-accounts](/concepts/projects) * [Authentication](/authentication#scopes) for the `billing:read` scope. * [Metrics and how they are calculated](/analytics/overview) for call outcomes rather than cost.