feat(webapp): unconfigured billing limit UX and default billing alerts

- Billing limit form starts with no option selected and no save button
  until the user picks one (unconfigured orgs only)
- Show the yellow no-limit banner on the billing-limits page itself with
  explanatory text and no action button
- Seed default billing alerts ($5, $100, $500, $1000, $2500) for orgs
  without any, lazily on page load plus an admin backfill endpoint

Author: kathiekiwi

.server-changes/default-billing-alerts.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: improvement
+---
+
+Organizations without billing alerts now get sensible default spend alert thresholds automatically, so you're notified before usage grows unexpectedly. You can adjust or remove them anytime in billing settings.

apps/webapp/app/components/billing/BillingLimitConfigSection.tsx

@@ -51,10 +51,15 @@ type BillingLimitActionData = {
 
 export function isBillingLimitFormDirty(input: {
   billingLimit: BillingLimitResult;
-  mode: "none" | "plan" | "custom";
+  mode: "" | "none" | "plan" | "custom";
   customAmount: string;
   cancelInProgressRuns: boolean;
 }): boolean {
+  // No mode selected yet (unconfigured limit) — nothing to save.
+  if (input.mode === "") {
+    return false;
+  }
+
   const needsInitialSave = !input.billingLimit.isConfigured;
   const savedMode = getBillingLimitMode(input.billingLimit);
   const savedCustomAmount =
@@ -75,7 +80,7 @@ export function isBillingLimitFormDirty(input: {
 
 export function getBillingLimitFormLastSubmission(
   submission: BillingLimitActionData["submission"] | undefined,
-  mode: "none" | "plan" | "custom",
+  mode: "" | "none" | "plan" | "custom",
   isDirty: boolean
 ) {
   if (!isDirty || !submission) {
@@ -111,17 +116,20 @@ export function BillingLimitConfigSection({
       : "";
   const savedCancelInProgressRuns = billingLimit.isConfigured && billingLimit.cancelInProgressRuns;
 
-  const [mode, setMode] = useState<"none" | "plan" | "custom">(savedMode);
+  // When no limit is configured yet, start with no radio option selected.
+  const resetMode: "" | "none" | "plan" | "custom" = billingLimit.isConfigured ? savedMode : "";
+
+  const [mode, setMode] = useState<"" | "none" | "plan" | "custom">(resetMode);
   const [customAmount, setCustomAmount] = useState(savedCustomAmount);
   const [cancelInProgressRuns, setCancelInProgressRuns] = useState(savedCancelInProgressRuns);
   const customAmountInputRef = useRef<HTMLInputElement>(null);
   const formRef = useRef<HTMLFormElement>(null);
 
   useEffect(() => {
-    setMode(savedMode);
+    setMode(resetMode);
     setCustomAmount(savedCustomAmount);
     setCancelInProgressRuns(savedCancelInProgressRuns);
-  }, [savedMode, savedCustomAmount, savedCancelInProgressRuns]);
+  }, [resetMode, savedCustomAmount, savedCancelInProgressRuns]);
 
   function handleModeChange(value: string) {
     const nextMode = value as typeof mode;
@@ -283,7 +291,7 @@ export function BillingLimitConfigSection({
             </div>
           </RadioGroup>
 
-          {mode !== "none" && (
+          {(mode === "plan" || mode === "custom") && (
             <CheckboxWithLabel
               className="mt-4"
               name="cancelInProgressRuns"
@@ -295,14 +303,16 @@ export function BillingLimitConfigSection({
               onChange={setCancelInProgressRuns}
             />
           )}
-          <FormButtons
-            className={isDirty ? undefined : "invisible"}
-            confirmButton={
-              <Button type="submit" variant="primary/small" disabled={!isDirty}>
-                Save billing limit
-              </Button>
-            }
-          />
+          {mode !== "" && (
+            <FormButtons
+              className={isDirty ? undefined : "invisible"}
+              confirmButton={
+                <Button type="submit" variant="primary/small" disabled={!isDirty}>
+                  Save billing limit
+                </Button>
+              }
+            />
+          )}
         </Fieldset>
       </Form>
     </div>

apps/webapp/app/components/billing/OrgBanner.tsx

@@ -63,7 +63,9 @@ export function OrgBanner() {
     case OrgBannerKind.LimitGrace:
       return hideBillingLimitBanner ? null : <LimitGraceBanner />;
     case OrgBannerKind.NoLimitConfigured:
-      return hideBillingLimitBanner ? null : <NoLimitConfiguredBanner />;
+      // On the billing-limits page we still surface the warning, but without the
+      // "Configure billing limit" action — the form is already on the page.
+      return <NoLimitConfiguredBanner onBillingLimitsPage={hideBillingLimitBanner} />;
     case OrgBannerKind.Upgrade:
       return organization ? <UpgradeBanner /> : null;
     case OrgBannerKind.EnvironmentWarning:
@@ -141,25 +143,29 @@ function LimitGraceBanner() {
   );
 }
 
-function NoLimitConfiguredBanner() {
+function NoLimitConfiguredBanner({ onBillingLimitsPage }: { onBillingLimitsPage: boolean }) {
   const organization = useOrganization();
   const canManageBillingLimits = useCanManageBillingLimits();
 
+  const message = canManageBillingLimits
+    ? onBillingLimitsPage
+      ? "Please configure a billing limit to protect your organization from unexpected usage spikes."
+      : "Protect your organization from unexpected usage spikes."
+    : "Billing limits are not configured for this organization. Contact an organization administrator to configure them.";
+
   return (
     <AnimatedOrgBannerBar
       show
       variant="warning"
       action={
-        canManageBillingLimits ? (
+        canManageBillingLimits && !onBillingLimitsPage ? (
           <LinkButton variant="tertiary/small" to={v3BillingLimitsPath(organization)}>
             Configure billing limit
           </LinkButton>
         ) : undefined
       }
     >
-      {canManageBillingLimits
-        ? "Protect your organization from unexpected usage spikes."
-        : "Billing limits are not configured for this organization. Contact an organization administrator to configure them."}
+      {message}
     </AnimatedOrgBannerBar>
   );
 }

apps/webapp/app/routes/_app.orgs.$organizationSlug.settings.billing-limits/route.tsx

@@ -24,6 +24,10 @@ import {
   thresholdValuesAreUnique,
 } from "~/components/billing/billingAlertsFormat";
 import { getSuggestedRecoveryLimitDollars } from "~/components/billing/billingLimitFormat";
+import {
+  billingAlertsLookUnconfigured,
+  buildDefaultBillingAlerts,
+} from "~/services/billingAlertsDefaults.server";
 import {
   BillingLimitConfigSection,
   billingLimitFormSchema,
@@ -126,15 +130,25 @@ export const loader = dashboardLoader(
       });
     }
 
-    const [alertsError, alerts] = await tryCatch(getBillingAlerts(organization.id));
-    if (alertsError || !alerts) {
+    const planLimitCents = currentPlan?.v3Subscription?.plan?.limits.includedUsage ?? 500;
+
+    const [alertsError, fetchedAlerts] = await tryCatch(getBillingAlerts(organization.id));
+    let alerts = alertsError ? undefined : fetchedAlerts;
+    if (
+      getBillingLimitMode(billingLimit) === "none" &&
+      (!alerts || billingAlertsLookUnconfigured(alerts))
+    ) {
+      // Lazily seed default alerts for orgs that have none configured.
+      const defaults = buildDefaultBillingAlerts();
+      const [seedError, seeded] = await tryCatch(setBillingAlert(organization.id, defaults));
+      alerts = seedError || !seeded ? defaults : seeded;
+    }
+    if (!alerts) {
       throw new Response(null, {
         status: 404,
         statusText: `Billing alerts error: ${alertsError ?? "not found"}`,
       });
     }
-
-    const planLimitCents = currentPlan?.v3Subscription?.plan?.limits.includedUsage ?? 500;
     const alertsResetRequested = getAlertsResetRequested(request);
     const resolveSubmitted = getResolveSubmitted(request);
     const submittedResumeMode = getSubmittedResumeMode(request);

apps/webapp/app/routes/admin.api.v1.billing-alerts.backfill.ts

@@ -0,0 +1,25 @@
+import { type ActionFunctionArgs, json } from "@remix-run/server-runtime";
+import { z } from "zod";
+import { backfillBillingAlerts } from "~/services/billingAlertsBackfiller.server";
+import { requireAdminApiRequest } from "~/services/personalAccessToken.server";
+
+const Body = z.object({
+  cursor: z.string().optional(),
+  batchSize: z.number().int().positive().max(500).optional(),
+  dryRun: z.boolean().optional(),
+});
+
+export async function action({ request }: ActionFunctionArgs) {
+  await requireAdminApiRequest(request);
+
+  try {
+    const body = await request.json();
+    const { cursor, batchSize, dryRun } = Body.parse(body);
+
+    const result = await backfillBillingAlerts({ cursor, batchSize, dryRun });
+
+    return json({ success: true, ...result });
+  } catch (error) {
+    return json({ error: error instanceof Error ? error.message : error }, { status: 400 });
+  }
+}

apps/webapp/app/services/billingAlertsBackfiller.server.ts

@@ -0,0 +1,107 @@
+import { tryCatch } from "@trigger.dev/core";
+import { prisma } from "~/db.server";
+import { logger } from "~/services/logger.server";
+import {
+  billingAlertsLookUnconfigured,
+  buildDefaultBillingAlerts,
+} from "~/services/billingAlertsDefaults.server";
+import { getBillingAlerts, getBillingLimit, setBillingAlert } from "~/services/platform.v3.server";
+
+export type BillingAlertsBackfillResult = {
+  orgCount: number;
+  seeded: number;
+  skipped: number;
+  failed: number;
+  /** Pass back as `cursor` to continue; undefined when done. */
+  cursor: string | undefined;
+};
+
+/** Seeds default billing alerts for orgs that have none configured. */
+export async function backfillBillingAlerts({
+  cursor,
+  batchSize = 50,
+  dryRun = false,
+}: {
+  cursor?: string;
+  batchSize?: number;
+  dryRun?: boolean;
+}): Promise<BillingAlertsBackfillResult> {
+  const orgs = await prisma.organization.findMany({
+    where: {
+      deletedAt: null,
+      ...(cursor ? { id: { gt: cursor } } : {}),
+    },
+    orderBy: { id: "asc" },
+    take: batchSize,
+    select: { id: true, slug: true },
+  });
+
+  let seeded = 0;
+  let skipped = 0;
+  let failed = 0;
+
+  for (const org of orgs) {
+    const [alertsError, alerts] = await tryCatch(getBillingAlerts(org.id));
+    if (alertsError || !alerts) {
+      logger.warn("backfillBillingAlerts: failed to get alerts, skipping org", {
+        organizationId: org.id,
+        error: alertsError instanceof Error ? alertsError.message : alertsError,
+      });
+      failed++;
+      continue;
+    }
+
+    if (!billingAlertsLookUnconfigured(alerts)) {
+      skipped++;
+      continue;
+    }
+
+    // Absolute-dollar defaults only apply when no billing limit is configured.
+    const [limitError, billingLimit] = await tryCatch(getBillingLimit(org.id));
+    if (limitError || !billingLimit) {
+      logger.warn("backfillBillingAlerts: failed to get billing limit, skipping org", {
+        organizationId: org.id,
+        error: limitError instanceof Error ? limitError.message : limitError,
+      });
+      failed++;
+      continue;
+    }
+
+    if (billingLimit.isConfigured && billingLimit.mode !== "none") {
+      skipped++;
+      continue;
+    }
+
+    const defaults = buildDefaultBillingAlerts();
+
+    if (dryRun) {
+      logger.info("backfillBillingAlerts: would seed defaults (dry run)", {
+        organizationId: org.id,
+        slug: org.slug,
+        defaults,
+      });
+      seeded++;
+      continue;
+    }
+
+    const [seedError] = await tryCatch(setBillingAlert(org.id, defaults));
+    if (seedError) {
+      logger.warn("backfillBillingAlerts: failed to seed defaults, skipping org", {
+        organizationId: org.id,
+        error: seedError instanceof Error ? seedError.message : seedError,
+      });
+      failed++;
+      continue;
+    }
+
+    seeded++;
+  }
+
+  return {
+    orgCount: orgs.length,
+    seeded,
+    skipped,
+    failed,
+    cursor: orgs.length === batchSize ? orgs[orgs.length - 1].id : undefined,
+  };
+}

apps/webapp/app/services/billingAlertsDefaults.server.ts

@@ -0,0 +1,41 @@
+import type { UpdateBillingAlertsRequest } from "@trigger.dev/platform";
+import { ABSOLUTE_ALERT_BASE_CENTS } from "~/components/billing/billingAlertsFormat";
+
+/** Default absolute alert thresholds in dollars. */
+const DEFAULT_ALERT_THRESHOLD_DOLLARS = [5, 100, 500, 1000, 2500];
+
+/**
+ * Build the default billing alerts for an org that has none configured.
+ *
+ * The platform evaluates alerts as `usage / amount >= level`. Setting `amount`
+ * to the $1 base (100 cents) turns `alertLevels` into absolute dollar thresholds,
+ * which is what the current "no limit configured" UI expects.
+ *
+ * Emails are left empty: the platform falls back to org admin/member addresses
+ * when no recipients are configured.
+ */
+export function buildDefaultBillingAlerts(): UpdateBillingAlertsRequest {
+  return {
+    amount: ABSOLUTE_ALERT_BASE_CENTS,
+    emails: [],
+    alertLevels: [...DEFAULT_ALERT_THRESHOLD_DOLLARS],
+  };
+}
+
+/**
+ * Whether alerts look never-configured. When no alert row exists the platform
+ * returns a default of `{ amount: planIncludedUsage, emails: [], alertLevels: [] }`;
+ * a deliberately cleared config stores the $1 absolute base amount and/or keeps
+ * the configured emails.
+ */
+export function billingAlertsLookUnconfigured(alerts: {
+  amount: number;
+  emails: string[];
+  alertLevels: number[];
+}): boolean {
+  return (
+    alerts.alertLevels.length === 0 &&
+    alerts.emails.length === 0 &&
+    alerts.amount !== ABSOLUTE_ALERT_BASE_CENTS
+  );
+}