Cross-platform rolling ad-spend cap that blocks overspend across multiple ad platforms combined, not just per-platform daily limits. Fails closed on unreadable spend data.
Most per-platform ad tools (Meta, TikTok, Google, etc.) only enforce their
own daily spend cap. If your agent runs ad spend across more than one
platform, none of them know about each other — total combined spend can
exceed what you actually intended even when every individual platform
"cap" is technically respected.
This skill adds one rolling-window cap that sums spend across all
platforms you configure, and blocks any spend action that would push the
combined total over your limit — regardless of which platform is asking.
Why fail-closed matters
If the spend ledger for a platform is corrupted, missing in an unexpected
way, or fails to parse, this skill treats that platform's spend as
unknown, not zero, and blocks new spend until it's resolved. A governor
that silently assumes "unreadable = $0 spent" will let real overspend
through at exactly the moment something is already wrong. This is the
single most important property of this skill — don't change it.
Setup
Copy ad_budget_governor.py into your project.
Edit LEDGER_PATHS to point at your own platform spend-tracking files.
Each ledger is a JSON file containing a list of records shaped like:
json
Extra fields are ignored. If your platform wrapper doesn't already log
spend in this shape, add that logging before wiring this in.
Call check_rolling_budget(amount_usd) before every spend action, on
every platform:
python
from ad_budget_governor import check_rolling_budget
ok, reason = check_rolling_budget(amount_usd=25.00)
if not ok:
# do not spend — surface `reason` to the operator
...
Set your cap (defaults to $0 — intentionally, so nothing spends before
a real number is chosen):
python
from ad_budget_governor import set_cap
set_cap(300.0, note="initial cap")
API
Function
Returns
check_rolling_budget(amount_usd)
(ok: bool, reason: str | None)
rolling_spend_usd(window_days=30)
(total: float, had_read_error: bool)
get_status()
dict with cap, spent, remaining, at_cap, ledger_read_error
set_cap(new_cap_usd, note="")
updated status dict
Tested against
Built and verified in production governing real Meta + TikTok ad spend for
a live marketing campaign before being generalized for publication here.