---
id: agencias/saldo-contas-de-anuncio
industry: Marketing agencies
usage: specific
effort: low
grain: Client x account, in a current snapshot and a daily history
---

# Ad account balances

How many business days of ads each prepaid account has left, with the top-up request going out in time for the client's Pix (instant payment) or boleto (bank slip) to clear before the campaign stops.

## Executive summary

**For:** Agencies running prepaid ad accounts that the client funds by Pix or boleto.

**What it solves**

- The top-up is requested while there is still time for the payment to clear.
- The reported balance is what the platform declares, not arithmetic between limit and spend.
- Postpaid accounts show the amount owed, never mixed with balance.

**Why it matters:** A prepaid account with no balance stops delivering immediately, and the client finds out from the drop in leads. Between requesting the top-up, the client approving, paying and the money clearing, business days go by. An alert that counts calendar days or reads the wrong field warns too late or warns all the time, and the team stops reading it.

**Business questions it answers**

- Which accounts will run out of balance this week?
- What is the current balance of client X's account and how long will it last?
- How much does each client need to top up to reach the end of the month?
- Which postpaid accounts have a high amount owed?
- Does the budget configured in the campaigns fit the net balance of the last top-up?

**What you need**

- Meta Ads and Google Ads connected to Nekt, with the accounts table and the activity log
- The account-to-client registry with each client's official accounts
- The payment window agreed with each client (in business days) and the fee on top-ups, if any

**What you get**

- A current table per client and account with payment model, balance, amount owed and business days until empty
- A daily balance history to see trends and check the alert
- Low and critical balance alerts, with state, for the team and the client
- An AI agent that answers about balance by reading the right field for each account type

## Detailed

### The problem

Meta's accounts table carries balance, spend_cap and amount_spent, but none of them is the balance of a prepaid account: the available balance only comes written inside a payment method text. On a postpaid account, balance is what is owed. Google stores budget limit and consumption as text in micros. Whoever computes balance as limit minus spend, or counts calendar days until empty, sends the top-up request on a Friday afternoon and the account stops on Saturday.

### Business rules

1. **Prepaid and postpaid answer different questions.** Classify each account by is_prepay_account. On prepaid, the question is available balance. On postpaid, it is the amount owed, stored as a positive number and shown with a negative sign only in presentation. Never add a prepaid balance to a postpaid amount owed. (Avoid: A single 'balance' column for every account.)
2. **Available balance is what Meta declares.** On a prepaid account, read the value from the 'Saldo disponível (...)' (available balance) text in funding_source_details.display_string. The balance field is not the prepaid balance, and spend_cap - amount_spent is not either: spend_cap is a spending limit and amount_spent is the lifetime spend of the account. If the text cannot be parsed safely (another currency, another language), the balance is null, never zero. Keep the raw balance under a neutral name for auditing. (Avoid: Balance = spend_cap - amount_spent, or the prepaid account's balance field.)
3. **Meta values in cents, Google in micros.** Meta's balance, amount_spent and spend_cap come in the currency's smallest unit: divide by 100. In Google, adjusted_spending_limit_micros and amount_served_micros come as text in micros: cast to number and divide by 1,000,000. Each account has its own currency; never sum different currencies. (Avoid: Reading balance as reais and summing accounts in reais and dollars.)
4. **In Google, balance is the most recent approved budget.** Use the account_budget row with status APPROVED and the most recent approved_start_date_time for the account. Balance = adjusted_spending_limit_micros - amount_served_micros, in reais. The connector does not bring individual top-ups: the budget is the approved total and the accumulated consumption. (Avoid: Summing every budget row of the account.)
5. **No balance in the API, use a ledger.** When the platform does not expose the balance, start from a reference balance checked on screen at a known moment. Current balance = reference + top-ups confirmed after it (event_type funding_event_successful in the activity log) - spend after it (hourly insights, starting from the first full hour after the reference). Reset the reference whenever the value diverges from the screen. (Avoid: Estimating the balance from the month's spend with no starting point.)
6. **The fee on top-ups comes out of the balance.** If a Pix top-up carries a tax (for example, 12.15%), the net balance is the amount paid x (1 - fee). Compare the daily budget configured in the campaigns with the net balance, not with the amount the client transferred. (Avoid: Planning the month with the full Pix amount.)
7. **Runway in business days, from recent spend.** Average spend = mean of the last 3 complete days (today is left out because the day is only half over). Days until empty = balance / average spend. Convert to business days, without weekends and holidays, because the client pays on business days. With no valid average spend, the status is undetermined, not infinite. (Avoid: Dividing the balance by today's spend and counting calendar days.)
8. **Bands follow the client's payment window.** Critical at 5 business days or fewer, the minimum to request, approve, pay and clear the top-up; low at 6 to 7 business days; ok above that. The window belongs to each client and lives in that client's context. The message to the client and the internal alert are different texts. (Avoid: A fixed threshold in reais for every account.)
9. **Only official accounts, and the source does not define the owner.** A source's accounts table lists everything the credential can see in the Business Manager. Filter by the official account_id from the registry. The source that brought the financial data may sit in another client's layer: never infer the account's owner from the source layer. Sum balances of different accounts only within the same snapshot and currency. (Avoid: Assigning the account to the client whose layer brought the table.)
10. **Current snapshot, history and stateful alert.** The current table has one row per client and account and says when it was generated; it does not answer yesterday's balance. In parallel, append a daily history. The alert stores the last status sent per account and only fires again when the status changes or worsens, with a send log. (Avoid: Reading trends from the current table and sending the same alert every day.)

### Which field answers the balance

By platform and account type.

- **Meta, prepaid** → Available balance (`funding_source_details.display_string`)
- **Meta, postpaid** → Amount owed, in cents (`balance / 100`)
- **Meta, spending limit** → Limit, not balance (`spend_cap`)
- **Meta, lifetime spend** → Spend over the account's life, not the period (`amount_spent`)
- **Meta, top-up** → Ledger entry (`funding_event_successful`)
- **Google, approved budget** → Budget balance (`adjusted_spending_limit_micros - amount_served_micros`)

### Definitions

| Metric | Definition |
|---|---|
| Available balance | value from the 'Saldo disponível' (available balance) text of the prepaid account's payment method, in the current snapshot, in the account's currency |
| Amount owed | balance / 100 of the postpaid account, positive, in the current snapshot |
| Net top-up balance | amount paid x (1 - fee on the top-up) |
| Recent average spend | sum of spend over the last 3 complete days / 3, per account |
| Days until empty | available balance / recent average spend |
| Business days until empty | business days (no weekends or holidays) between today and the estimated date the balance runs out |
| Balance status | critical up to 5 business days, low from 6 to 7, ok above 7, undetermined with no valid average spend (bands adjustable per client) |

### Pitfalls

- **A balance that was a limit.** Balance computed as spending limit minus lifetime spend goes negative on accounts with no limit (spend_cap zero) and, on the others, has nothing to do with the available credit. How to avoid: Read the balance Meta declares; limit and lifetime spend do not make a balance.
- **A zero balance that was not zero.** On prepaid accounts, balance comes as zero and the balance is only written in the payment method text. A monitor that reads balance flags every prepaid account as empty. How to avoid: Extract the value from the available balance text and leave it null when that fails.
- **Friday warning for an account that stopped on Saturday.** Runway was counted in calendar days. The top-up request went out with two days to spare, which fell on the weekend. How to avoid: Count in business days, with the client's payment window.
- **Budget bigger than the Pix.** The budget configured in the campaigns was planned with the full Pix amount, but the top-up arrived net of the fee and the money ran out before month end. How to avoid: Compare the configured budget with the net balance.
- **Average dragged down by today.** The spend average included the half-finished current day and underestimated the pace, pushing the run-out date forward. How to avoid: Use only complete days in the average.
- **Spend counted before the reference.** With the reference balance checked in the middle of an hour, that whole hour's spend enters the ledger and the balance ends up below what the screen shows. How to avoid: Count spend from the first full hour after the reference.

Validated on real data: In Nekt's own Meta Ads account, the accounts table returned 9 accounts in three currencies, two of them closed. On the prepaid accounts, balance came as zero and the balance only appeared in the 'Saldo disponível (...)' text of funding_source_details.display_string. On the postpaid card account, balance was the amount owed, in cents.

### Acceptance test

- [ ] For each prepaid account, the available balance in the table equals what Ads Manager shows at snapshot time.
- [ ] No prepaid account has a balance computed from spend_cap or amount_spent.
- [ ] The current table has one row per client and official account, and no account outside the registry.
- [ ] Business days until empty is never below zero and is undetermined when there are not 3 complete days of spend.
- [ ] Each account gets at most one alert per status change.

### Context document

```text
Ad account balances
- Prepaid account (is_prepay_account true): 'balance' = value from the 'Saldo disponível' (available balance) text in funding_source_details.display_string. If it is not available, say the balance was not obtained. Never use balance, spend_cap or amount_spent as the balance.
- Postpaid account: balance / 100 is the amount owed. Show it with a negative sign only if asked for 'positive and negative balance'.
- Meta values in cents; Google in micros. Do not sum different currencies.
- Google: balance = adjusted_spending_limit_micros - amount_served_micros of the most recent APPROVED budget.
- Business days until empty = balance / average spend of the last 3 complete days, counted in business days.
- Status: critical up to 5 business days, low from 6 to 7, ok above. No valid average: undetermined.
- The current table does not answer past balances. Use the daily history.
- Only accounts in each client's registry. The source layer does not define the account's owner.
Client exceptions:
- <client>: Pix top-up with a <x>% fee; net balance = paid x (1 - fee).
- <client>: payment window of <n> business days; critical below <n>.
```

### Variations

- **Suggested top-up:** Amount to reach month end = average spend x days left - balance, with the top-up fee already added.
- **Pace against the plan:** Compare average spend with the media plan's daily budget to know whether the top-up covers what was planned.
- **Postpaid account:** Alert when the amount owed approaches the billing threshold or when the account changes status after a payment failure.