Account spend policies
Preview, apply and roll back Cloudflare spending alerts and spending limits for Workers and Durable Objects with quickback platform budget.
quickback platform budget manages Cloudflare spend policies: email alerts
and spending limits for Workers and Durable Objects. It wraps the official
cf billing spend-policies
commands in a preview, review and apply workflow. Each change is checked
against the policy's version and recorded in a local receipt.
These are account-level platform controls. Each policy covers one product (all Workers, or all Durable Objects) across one Cloudflare account. A policy cannot target one Worker, one Durable Object namespace or one tenant, so it is not a per-tenant quota. It is also not an invoice cap. Usage reporting and blocking take time, and some charges continue during a pause, so the invoice can exceed the threshold.
What Cloudflare supports
| Control | Supported here | Notes |
|---|---|---|
Workers or Durable Objects email alert (notification) | Yes | Emails at 80% and 100% of the threshold. The product keeps running. |
Workers or Durable Objects spending limit (usage_block) | Yes | Blocks the product's supported operations across the account. One enabled limit per product. |
| Account-wide budget alert | No | Dashboard only (Billing → Billable Usage). Cloudflare has no CLI or API for it, so a budgetAlerts key in the document is a validation error. |
| Current recorded spend | No | cf has no command that reads current spend. Plans and status show it as unknown, and show the latest 80% and 100% threshold events instead. |
Spend policies do not cover the Workers Paid subscription fee, Workers KV, R2, D1, Queues, Workers AI, Vectorize or Durable Objects stored data.
A Workers limit can stop HTTP requests, cron triggers, queue consumers and other invocations for every Worker on the account. A Durable Objects limit pauses requests and operations. Existing WebSockets and some work in progress can continue. See Cloudflare's notes on Workers and Durable Objects.
Prerequisites
- The
cfCLI, signed in or withCLOUDFLARE_API_TOKENset. - Account → Billing → Read to run
status,planandhistory. Billing → Edit to runapply. Cloudflare checks these permissions, not Quickback.
The account is always explicit
Every command needs --account <id>, or --env <target> to use that target's
accountId from quickback.config.ts. Quickback never takes the account from
your current cf or Wrangler login. The first line of output names the
account. Each cf call runs with CLOUDFLARE_ACCOUNT_ID set to that account,
which overrides any ambient value (Quickback prints a warning when it does).
Your global cf profile is not modified.
With --env, the plan also lists the other deployment targets on the same
account, because a limit stops all of them.
The budget document
Policies are declared in a JSON file that operators own. It is kept apart from
quickback.config.ts, because one account can host several projects, and
quickback build and quickback deploy never apply account policies.
{
"version": 1,
"owner": "platform-ops",
"accountId": "0123456789abcdef0123456789abcdef",
"policies": [
{ "key": "workers-alert", "product": "workers", "action": "notification", "thresholdCents": 5000, "enabled": true, "email": "ops@example.com" }
]
}This example sets an alert only. The amounts and addresses on this page are illustrations, not recommendations. To add a limit, choose it deliberately:
{ "key": "objects-limit", "product": "durable_objects", "action": "usage_block", "thresholdCents": 10000, "enabled": true, "email": "ops@example.com" }| Field | Rules |
|---|---|
owner | Lowercase slug naming the team that owns these policies. It labels ownership. It does not grant permission. |
accountId | 32 lowercase hex characters. Must equal --account or the --env target's account. |
key | Unique lowercase slug. Quickback tracks ownership by (account, owner, key), never by display name. |
product | workers or durable_objects. No other product supports spend policies. |
action | notification (alert) or usage_block (limit). |
thresholdCents | Positive whole number of US cents (5000 = $50). Zero, fractions and strings are rejected. |
enabled | Required true or false. |
email | One address. Required for alerts. A limit without one sends no email. |
name | Optional display name (1–200 bytes). Defaults to quickback <owner>/<key>. |
adoptPolicyId | Optional. Takes ownership of an existing policy, previewed in the plan like any other change. |
Unknown keys fail validation, and the CLI reports every problem at once. Never put API tokens in this file.
Plan, review, apply
quickback platform budget plan budget.json --out budget-plan.json --account 0123456789abcdef0123456789abcdef
quickback platform budget apply budget-plan.json --confirm <digest> --account 0123456789abcdef0123456789abcdefplan is read-only. It lists:
- every policy on the account, marked as owned or not owned;
- recorded spend as
unknown; - each operation, with before and after state, recipients, and its expected policy version;
- consequences, such as "can block every Worker invocation as soon as Cloudflare evaluates it", "lowers the threshold" or "lifts any block and permits further spending";
- a SHA-256 digest of the whole plan file.
plan refuses to:
- create a second enabled limit for a product while a policy it does not own is already one. Turn that policy off, or adopt it explicitly;
- change a policy's product;
- adopt a policy that is already owned.
When you remove an owned policy from the document, the plan turns it off rather than deleting it.
apply checks the --confirm digest against the plan file, so a file edited
after review is refused. It then reads every policy again before changing
anything. A policy at a different version than the plan expected stops the
run: re-plan and review the new state. Quickback never merges changes made by
another operator. Each update resends the whole policy, as Cloudflare requires,
with --if-match <version>.
Ownership and receipts
Operator state lives in --state (default .quickback/platform-budget/).
Files are written with mode 0600:
ownership.jsonmaps(account, owner, key)to the policy id, the last version Quickback saw, and a configuration hash. When a policy was changed outside Quickback, the next plan says so.receipts.jsonlis append-only. Quickback writes anintentline before each change and adoneline after it, with the before and after state and the version Cloudflare returned. If theintentwrite fails, nothing is sent to Cloudflare. If thedonewrite fails after Cloudflare accepted a change,applystops and names the policy and version.
Keep this directory somewhere durable and private. If several operators apply changes, share it, for example in a private repository. Receipts contain notification email addresses.
Partial failure and resume
Each policy is changed separately, so partial success is possible. apply
lists the operations that completed, the one that failed, and those not yet
tried. To resume, run the same apply again. It skips operations that already
completed. If the failure was a version conflict (HTTP 412), re-plan instead.
If a create's response is lost, its outcome is unknown. On the next run,
apply looks for exactly one policy it does not own that matches the create.
If it finds one, it records it and does not create it again. If it finds more
than one, it stops. Check history before trying again.
Rollback
quickback platform budget rollback-plan budget-plan.json --out rollback.json --account 0123456789abcdef0123456789abcdef
quickback platform budget apply rollback.json --confirm <digest> --account 0123456789abcdef0123456789abcdefRollback does not clean up automatically. It builds a new plan for you to review:
- a changed policy goes back to the full state recorded before it was changed;
- a created policy is turned off.
rollback-plan refuses if a policy changed after the original apply, rather
than overwriting that edit. It also refuses if the policy's ownership no longer
matches the receipt. Raising or turning off a limit permits further spending,
and the plan says so.
Status and history
quickback platform budget status --account 0123456789abcdef0123456789abcdef --json
quickback platform budget history --account 0123456789abcdef0123456789abcdef
quickback platform budget history --account 0123456789abcdef0123456789abcdef --policy <policy-id>status lists each policy, whether Quickback owns it, and its latest threshold
event. history with no --policy shows configuration changes across the
account: who made them, with before and after settings (--cursor pages, and
--limit accepts up to 100). With --policy, it shows that policy's threshold
events.
Keep these states apart:
- Configuration. Read-back after
applyconfirms the settings Cloudflare stored. - Threshold events.
approaching_limit(80%) andlimit_reached(100%) record that Cloudflare evaluated the policy. They do not confirm that blocking finished or that an email was delivered. If spend jumps past both thresholds between evaluations, only the 100% email may arrive. - Enforcement. An enabled policy is not proof that the product is running,
and
limit_reachedis not proof that it has stopped.
After a prolonged Durable Objects block
When service returns, by raising the limit, turning it off or reaching the next billing period:
- Check
history --policy <id>for when the limit was reached. - Durable Object alarms held for more than seven days during a pause can be removed. Reconcile any job, schedule or retry that depends on an alarm, and re-arm alarms from your application's own state.
- Check queue consumers and cron-driven work for runs that were skipped while Workers were blocked.
- Clients holding WebSockets that stayed open may have missed events. Have them resynchronize.
Workload controls in quickback.config.ts
Spend policies are account-wide. To limit one Worker, set
providers.runtime.config.limits.cpuMs in the project config. It sets the CPU
time one invocation may use, emitted as limits.cpu_ms (see
Runtime options). It stops runaway work
in a single request. It does not cap spend.