docs: billing limits and alerts page (#4132)

New `/billing-limits` page covering the full [billing limits
feature](https://trigger.dev/changelog/billing-limits) : the three limit
options (plan / custom / no limit), billing alerts (% of limit or dollar
thresholds), what happens when the limit is reached, the recovery flow,
the soft-limits caveat, and the billing limit marker on the Usage page.

Author: kathiekiwi

docs/billing-limits.mdx

@@ -0,0 +1,73 @@
+---
+title: "Billing limits and alerts"
+sidebarTitle: "Billing limits & alerts"
+description: "Set a monthly compute spend cap for your organization and get email alerts before you reach it."
+---
+
+Billing limits let you cap your organization's monthly compute spend so a runaway task or unexpected traffic spike can't blow your budget. Billing alerts notify you by email as you approach thresholds you choose.
+
+<Note>Billing limits and alerts are available to all [Trigger.dev Cloud](https://trigger.dev) organizations. They don't apply to self-hosted instances.</Note>
+
+You can find the settings in the dashboard: open the **Organization** menu in the top left, then **Settings** → **Billing limits**.
+
+<picture>
+  <source srcSet="/images/billing-docs.webp" type="image/webp" />
+  <img src="/images/billing-docs.png" alt="Billing limit settings" />
+</picture>
+
+## Setting a billing limit
+
+Choose one of three options:
+
+- **Plan limit**: Use your plan's maximum as the spending cap.
+- **Custom limit**: Set your own monthly spend threshold.
+- **No limit**: No cap is enforced. This is the default.
+
+A billing limit applies to your whole organization and covers billable environments: `production`, `staging`, and `preview`. Your `dev` environment is not affected.
+
+Optionally, enable **Cancel in-progress runs when this limit is reached** to immediately cancel executing runs when the limit is hit, instead of letting them finish naturally.
+
+## Billing alerts
+
+Billing alerts are email notifications sent when your monthly spend crosses a threshold. You can add multiple thresholds:
+
+- **With a billing limit set**: thresholds are percentages of your limit (e.g. 50%, 80%).
+- **Without a billing limit**: thresholds are dollar amounts.
+
+<picture>
+  <source srcSet="/images/billing-alerts-docs.webp" type="image/webp" />
+  <img src="/images/billing-alerts-docs.png" alt="Billing alerts settings" />
+</picture>
+
+Alerts only notify you — they never pause environments or reject runs. Use them on their own for visibility, or alongside a limit to get advance warning before enforcement kicks in.
+
+## What happens when you reach your limit
+
+When your organization's spend reaches the billing limit, billable environments enter a **grace period**:
+
+1. Queues pause across `production`, `staging`, and `preview`. In-progress runs finish naturally (unless you enabled **Cancel in-progress runs**).
+2. New runs can still be triggered and are queued, but they won't start executing. Queued runs incur no compute cost until they start.
+3. You have **24 hours** to review and decide what to do.
+
+If you don't act before the grace period ends, queued runs are canceled and new triggers are rejected for the rest of the billing cycle.
+
+<Note>
+  Billing limits are **soft limits**, not instantaneous hard caps. Usage is evaluated on a short
+  delay, so spend can briefly exceed your limit before enforcement applies. See our
+  [terms](https://trigger.dev/terms) for refund policy details.
+</Note>
+
+## Resuming after hitting a limit
+
+To resume execution, increase or remove the billing limit from the **Billing limits** page. You'll be asked what to do with the runs that queued up during the pause:
+
+- **Resume queued runs**: everything that built up during the pause runs in order.
+- **Cancel queued runs**: the backlog is discarded and only new triggers run going forward.
+
+Execution resumes automatically once you've resolved the limit. Limits also reset at the start of each billing cycle.
+
+## Tracking spend against your limit
+
+On the **Usage** page (Organization menu → **Usage**), a **Billing limit** marker appears on the usage bar alongside your current spend and plan included usage, so you can see how close you are at a glance.
+
+For tips on lowering your spend in the first place, see [How to reduce your spend](/how-to-reduce-your-spend).

docs/docs.json

@@ -255,7 +255,13 @@
           },
           {
             "group": "Using the Dashboard",
-            "pages": ["run-tests", "troubleshooting-alerts", "replaying", "bulk-actions"]
+            "pages": [
+              "run-tests",
+              "troubleshooting-alerts",
+              "billing-limits",
+              "replaying",
+              "bulk-actions"
+            ]
           },
           {
             "group": "Troubleshooting",

docs/how-to-reduce-your-spend.mdx

@@ -24,20 +24,7 @@ Configure billing limits and alerts in your dashboard to protect against unexpec
 - Catch unexpected cost increases early
 - Identify runaway tasks before they become expensive
 
-The **Billing limits** settings page has two sections:
-
-- **Billing limit**: Choose your plan limit, a custom amount, or no limit. When a limit is reached, billable environments (`production`, `staging`, and `preview`) enter a **grace period** — queues pause and new runs queue without starting. After grace expires, new triggers are rejected until you increase or remove the limit.
-- **Billing alerts**: Add email alerts at specific spend thresholds (% of your limit when a limit is set, or dollar amounts when no limit is configured). Alerts notify you only; they do **not** pause environments or reject triggers.
-
-**Limits vs alerts:** A billing limit enforces spend (grace → reject). Billing alerts are optional notifications at thresholds you choose.
-
-**Soft limits:** Billing limits are not instantaneous hard caps. Usage is evaluated on a short delay, so spend can briefly exceed your limit before enforcement applies. Queued runs during grace incur no compute cost until they start. See our [terms](https://trigger.dev/terms) for refund policy details.
-
-On the **Usage** page, when you have a custom billing limit (or a plan limit that differs from included usage), a **Billing limit** marker appears on the usage bar alongside your current spend and plan included usage.
-
-![Billing limits and alerts settings](./images/billing-alerts-ui.png)
-
-You can open the page from the **Organization** menu in the top left of the dashboard, then **Settings** → **Billing limits**.
+You can open the settings from the **Organization** menu in the top left of the dashboard, then **Settings** → **Billing limits**. [Read the full billing limits and alerts docs](/billing-limits) for how limits are enforced, the grace period, and resuming after hitting a limit.
 
 ## Reduce your machine sizes
 

docs/images/billing-alerts-docs.png

@@ -7,6 +7,11 @@ import RateLimitHitUseBatchTrigger from "/snippets/rate-limit-hit-use-batchtrigg
 
 You can view your current limits, quotas, and rate limit usage in real-time by visiting the **Limits** page in the dashboard (accessible from the left sidebar). This page shows current rate limit token availability, quota usage, and plan features for your organization.
 
+<Note>
+  Looking to cap your monthly spend? That's a setting you control, not a platform limit — see
+  [Billing limits and alerts](/billing-limits).
+</Note>
+
 ## Concurrency limits
 
 | Pricing tier | Limit                |

docs/images/billing-alerts-docs.webp

@@ -242,6 +242,10 @@ If runs are staying in the `QUEUED` state for extended periods, check your concu
 - **Review queue concurrency limits** - Check if individual queues have restrictive `concurrencyLimit` settings
 - **Check for stuck runs** - See if stalled runs are blocking new executions
 
+### Runs queued because a billing limit was reached
+
+If your organization reaches a billing limit, billable environments (`production`, `staging`, and `preview`) pause: new runs still queue, but they won't start executing until you raise or remove the limit and choose whether to resume or cancel the queued runs. See [Billing limits and alerts](/billing-limits) for the full flow.
+
 ### `Crypto is not defined`
 
 This can happen in different situations, for example when using plain strings as idempotency keys. Support for `Crypto` without a special flag was added in Node `v19.0.0`. You will have to upgrade Node - we recommend even-numbered major releases, e.g. `v20` or `v22`. Alternatively, you can switch from plain strings to the `idempotencyKeys.create` SDK function. [Read the guide](/idempotency).