feat(webapp): show the billing limit on the usage page, with docs and tests

Add the usage-bar marker, documentation, and test coverage.

Author: kathiekiwi

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

@@ -53,8 +53,7 @@ export const billingAlertsSchema = z.object({
     const values = typeof i === "string" ? [i] : Array.isArray(i) ? i : [];
     return values
       .filter((v) => v !== "")
-      .map((v) => Number(v))
-      .filter((n) => Number.isFinite(n));
+      .map((v) => Number(v));
   }, z.number().array().refine(thresholdValuesAreUnique, "Each alert must be unique")),
 });
 

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

@@ -9,6 +9,7 @@ import {
   useOptionalOrganization,
   useOrganization,
   useBillingLimit,
+  useCanManageBilling,
 } from "~/hooks/useOrganizations";
 import { useOptionalProject, useProject } from "~/hooks/useProject";
 import { useShowSelfServe } from "~/hooks/useShowSelfServe";
@@ -17,7 +18,7 @@ import { v3BillingLimitsPath, v3BillingPath, v3QueuesPath } from "~/utils/pathBu
 
 function getUpgradeResetDate(): Date {
   const nextMonth = new Date();
-  nextMonth.setUTCMonth(nextMonth.getMonth() + 1);
+  nextMonth.setUTCMonth(nextMonth.getUTCMonth() + 1);
   nextMonth.setUTCDate(1);
   nextMonth.setUTCHours(0, 0, 0, 0);
   return nextMonth;
@@ -129,18 +130,23 @@ function LimitGraceBanner() {
 
 function NoLimitConfiguredBanner() {
   const organization = useOrganization();
+  const canManageBilling = useCanManageBilling();
 
   return (
     <AnimatedOrgBannerBar
       show
       variant="warning"
       action={
-        <LinkButton variant="tertiary/small" to={v3BillingLimitsPath(organization)}>
-          Configure billing limit
-        </LinkButton>
+        canManageBilling ? (
+          <LinkButton variant="tertiary/small" to={v3BillingLimitsPath(organization)}>
+            Configure billing limit
+          </LinkButton>
+        ) : undefined
       }
     >
-      Protect your organization from unexpected usage spikes.
+      {canManageBilling
+        ? "Protect your organization from unexpected usage spikes."
+        : "Billing limits are not configured for this organization. Contact an organization administrator to configure them."}
     </AnimatedOrgBannerBar>
   );
 }

apps/webapp/app/components/billing/billingAlertsFormat.ts

@@ -18,7 +18,7 @@ export type BillingLimitMode = "plan" | "custom" | "none";
 
 export function getBillingLimitMode(billingLimit: BillingLimitResult): BillingLimitMode {
   if (!billingLimit.isConfigured) {
-    return "plan";
+    return "none";
   }
   return billingLimit.mode;
 }
@@ -240,14 +240,16 @@ export function normalizeBillingAlertsFromApi(apiAlerts: {
   // Platform API stores amount in cents.
   let amountDollars = rawAmount / 100;
 
-  // Legacy percentage alerts sometimes stored plan dollars directly (e.g. 100 for $100).
-  // Never apply to absolute dollar alerts — those use a fixed $1 base (100 cents).
+  // Legacy percentage alerts sometimes stored plan dollars directly (e.g. 100 for $100)
+  // with whole-number percents (10, 50, 80). New saves store cents and fractional levels
+  // (0.75, 0.9) via thresholdsToAlertPayload — never treat those as legacy dollars.
   if (
     rawAmount !== ABSOLUTE_ALERT_BASE_CENTS &&
     Number.isFinite(rawAmount) &&
     rawAmount >= 10 &&
     rawAmount / 100 < 10 &&
-    alertLevels.length > 0
+    alertLevels.length > 0 &&
+    !usesFractionAlertLevelFormat(alertLevels)
   ) {
     amountDollars = rawAmount;
   }
@@ -311,11 +313,8 @@ export function storedAlertsToThresholds(
     return [];
   }
 
-  // Legacy percentage alerts keep their saved base amount even if billing limit changed.
-  if (
-    percentageAlertAmountMatches(amountCents, effectiveLimitCents, planLimitCents) ||
-    amountCents > 0
-  ) {
+  // Saved percentage alerts keep their thresholds whenever a positive base amount is stored.
+  if (amountCents > 0) {
     return uiThresholds.slice(0, MAX_PERCENTAGE_ALERTS);
   }
 

apps/webapp/app/components/billing/selectOrgBanner.ts

@@ -31,14 +31,16 @@ export function selectOrgBanner(input: {
     if (status === "grace") {
       return OrgBannerKind.LimitGrace;
     }
-  } else if (billingLimit && !billingLimit.isConfigured && showSelfServe) {
-    return OrgBannerKind.NoLimitConfigured;
   }
 
   if (hasExceededFreeTier) {
     return OrgBannerKind.Upgrade;
   }
 
+  if (billingLimit && !billingLimit.isConfigured && showSelfServe) {
+    return OrgBannerKind.NoLimitConfigured;
+  }
+
   if (showEnvironmentWarning) {
     return OrgBannerKind.EnvironmentWarning;
   }

apps/webapp/app/components/layout/AppLayout.tsx

@@ -1,3 +1,4 @@
+import { forwardRef } from "react";
 import { cn } from "~/utils/cn";
 
 /** This container is used to surround the entire app, it correctly places the nav bar */
@@ -34,17 +35,17 @@ export function PageContainer({
   );
 }
 
-export function PageBody({
-  children,
-  scrollable = true,
-  className,
-}: {
-  children: React.ReactNode;
-  scrollable?: boolean;
-  className?: string;
-}) {
+export const PageBody = forwardRef<
+  HTMLDivElement,
+  {
+    children: React.ReactNode;
+    scrollable?: boolean;
+    className?: string;
+  }
+>(function PageBody({ children, scrollable = true, className }, ref) {
   return (
     <div
+      ref={ref}
       className={cn(
         scrollable
           ? "overflow-y-auto p-3 scrollbar-thin scrollbar-track-transparent scrollbar-thumb-charcoal-600"
@@ -55,7 +56,7 @@ export function PageBody({
       {children}
     </div>
   );
-}
+});
 
 export function MainCenteredContainer({
   children,

apps/webapp/app/hooks/useOrganizations.ts

@@ -95,3 +95,11 @@ export function useBillingLimit(matches?: UIMatch[]) {
   });
   return data?.billingLimit;
 }
+
+export function useCanManageBilling(matches?: UIMatch[]) {
+  const data = useTypedMatchesData<typeof orgLoader>({
+    id: "routes/_app.orgs.$organizationSlug",
+    matches,
+  });
+  return data?.canManageBilling === true;
+}

apps/webapp/app/hooks/useScrollContainerToTop.ts

@@ -0,0 +1,14 @@
+import { useLocation } from "@remix-run/react";
+import { useEffect, useRef } from "react";
+
+/** Scroll a page body container back to the top when navigating to a route. */
+export function useScrollContainerToTop<T extends HTMLElement>() {
+  const ref = useRef<T>(null);
+  const location = useLocation();
+
+  useEffect(() => {
+    ref.current?.scrollTo(0, 0);
+  }, [location.key]);
+
+  return ref;
+}

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.queues/route.tsx

@@ -183,24 +183,22 @@ export const action = async ({ request, params }: ActionFunctionArgs) => {
   }
 
   switch (action) {
-    case "environment-pause":
+    case "environment-pause": {
       const pauseService = new PauseEnvironmentService();
-      {
-        const result = await pauseService.call(environment, "paused");
-        if (!result.success) {
-          return redirectWithErrorMessage(redirectPath, request, result.error);
-        }
+      const result = await pauseService.call(environment, "paused");
+      if (!result.success) {
+        return redirectWithErrorMessage(redirectPath, request, result.error);
       }
       return redirectWithSuccessMessage(redirectPath, request, "Environment paused");
-    case "environment-resume":
+    }
+    case "environment-resume": {
       const resumeService = new PauseEnvironmentService();
-      {
-        const result = await resumeService.call(environment, "resumed");
-        if (!result.success) {
-          return redirectWithErrorMessage(redirectPath, request, result.error);
-        }
+      const result = await resumeService.call(environment, "resumed");
+      if (!result.success) {
+        return redirectWithErrorMessage(redirectPath, request, result.error);
       }
       return redirectWithSuccessMessage(redirectPath, request, "Environment resumed");
+    }
     case "queue-pause":
     case "queue-resume": {
       const friendlyId = formData.get("friendlyId");

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

@@ -3,8 +3,6 @@ import type { MetaFunction } from "@remix-run/react";
 import {
   json,
   redirect,
-  type ActionFunction,
-  type LoaderFunctionArgs,
 } from "@remix-run/server-runtime";
 import { tryCatch } from "@trigger.dev/core";
 import { typedjson, useTypedLoaderData } from "remix-typedjson";
@@ -43,6 +41,7 @@ import { NavBar, PageAccessories, PageTitle } from "~/components/primitives/Page
 import { prisma } from "~/db.server";
 import { featuresForRequest } from "~/features.server";
 import { useScrollContainerToTop } from "~/hooks/useScrollContainerToTop";
+import { resolveOrgIdFromSlug } from "~/models/organization.server";
 import {
   commitSession,
   getSession,
@@ -59,6 +58,7 @@ import {
   setBillingAlert,
   setBillingLimit,
 } from "~/services/platform.v3.server";
+import { dashboardAction, dashboardLoader } from "~/services/routeBuilders/dashboardBuilder";
 import type { BillingLimitResult } from "~/services/billingLimit.schemas";
 import {
   getAlertsResetRequested,
@@ -77,15 +77,31 @@ import {
   v3BillingLimitsPath,
   v3BillingPath,
 } from "~/utils/pathBuilder";
-import { requireUserId } from "~/services/session.server";
+
+const billingLimitsAuthorization = {
+  action: "manage" as const,
+  resource: { type: "billing" as const },
+};
 
 export const meta: MetaFunction = () => {
   return [{ title: `Billing limits | Trigger.dev` }];
 };
 
-export async function loader({ params, request }: LoaderFunctionArgs) {
-  const userId = await requireUserId(request);
-  const { organizationSlug } = OrganizationParamsSchema.parse(params);
+export const loader = dashboardLoader(
+  {
+    params: OrganizationParamsSchema,
+    context: async (params) => {
+      const organizationId = await resolveOrgIdFromSlug(params.organizationSlug);
+      return organizationId ? { organizationId } : {};
+    },
+    authorization: {
+      ...billingLimitsAuthorization,
+      message: "With your current role, you can't manage billing limits.",
+    },
+  },
+  async ({ params, request, user }) => {
+  const userId = user.id;
+  const { organizationSlug } = params;
 
   const { isManagedCloud } = featuresForRequest(request);
   if (!isManagedCloud) {
@@ -131,9 +147,9 @@ export async function loader({ params, request }: LoaderFunctionArgs) {
   firstDayOfMonth.setUTCHours(0, 0, 0, 0);
 
   const firstDayOfNextMonth = new Date();
-  firstDayOfNextMonth.setUTCMonth(firstDayOfNextMonth.getUTCMonth() + 1);
   firstDayOfNextMonth.setUTCDate(1);
   firstDayOfNextMonth.setUTCHours(0, 0, 0, 0);
+  firstDayOfNextMonth.setUTCMonth(firstDayOfNextMonth.getUTCMonth() + 1);
 
   const [usage, queuedRunCount, billingLimitPauseEnvCount] = await Promise.all([
     getCachedUsage(organization.id, { from: firstDayOfMonth, to: firstDayOfNextMonth }),
@@ -166,7 +182,8 @@ export async function loader({ params, request }: LoaderFunctionArgs) {
     submittedResumeMode,
     suggestedNewLimitDollars,
   });
-}
+  }
+);
 
 type LoaderData = {
   billingLimit: BillingLimitResult;
@@ -182,9 +199,18 @@ type LoaderData = {
   suggestedNewLimitDollars: number;
 };
 
-export const action: ActionFunction = async ({ request, params }) => {
-  const userId = await requireUserId(request);
-  const { organizationSlug } = OrganizationParamsSchema.parse(params);
+export const action = dashboardAction(
+  {
+    params: OrganizationParamsSchema,
+    context: async (params) => {
+      const organizationId = await resolveOrgIdFromSlug(params.organizationSlug);
+      return organizationId ? { organizationId } : {};
+    },
+    authorization: billingLimitsAuthorization,
+  },
+  async ({ request, params, user }) => {
+  const userId = user.id;
+  const { organizationSlug } = params;
 
   const organization = await prisma.organization.findFirst({
     where: { slug: organizationSlug, members: { some: { userId } } },
@@ -476,7 +502,8 @@ export const action: ActionFunction = async ({ request, params }) => {
   }
 
   return json({ error: "Unknown form intent" }, { status: 400 });
-};
+  }
+);
 
 export default function Page() {
   const {

apps/webapp/app/routes/_app.orgs.$organizationSlug.settings.usage/route.tsx

@@ -6,6 +6,7 @@ import { Suspense, useMemo } from "react";
 import { redirect, typeddefer, useTypedLoaderData } from "remix-typedjson";
 import { URL } from "url";
 import { UsageBar } from "~/components/billing/UsageBar";
+import { getUsageBarBillingLimitDollars } from "~/components/billing/billingAlertsFormat";
 import { PageBody, PageContainer } from "~/components/layout/AppLayout";
 import { Card } from "~/components/primitives/charts/Card";
 import type { ChartConfig } from "~/components/primitives/charts/Chart";
@@ -30,6 +31,7 @@ import { useSearchParams } from "~/hooks/useSearchParam";
 import { UsagePresenter, type UsageSeriesData } from "~/presenters/v3/UsagePresenter.server";
 import { requireUserId } from "~/services/session.server";
 import { formatCurrency, formatCurrencyAccurate, formatNumber } from "~/utils/numberFormatter";
+import { useBillingLimit } from "~/hooks/useOrganizations";
 import { OrganizationParamsSchema, organizationPath } from "~/utils/pathBuilder";
 import { useCurrentPlan } from "../_app.orgs.$organizationSlug/route";
 
@@ -96,6 +98,11 @@ const monthDateFormatter = new Intl.DateTimeFormat("en-US", {
 export default function Page() {
   const { usage, tasks, months, isCurrentMonth } = useTypedLoaderData<typeof loader>();
   const currentPlan = useCurrentPlan();
+  const billingLimit = useBillingLimit();
+  const planLimitCents = currentPlan?.v3Subscription?.plan?.limits.includedUsage ?? 0;
+  const billingLimitDollars = isCurrentMonth
+    ? getUsageBarBillingLimitDollars(billingLimit, planLimitCents)
+    : undefined;
   const { value, replace } = useSearchParams();
 
   const month = value("month") ?? months[0].toISOString();
@@ -156,10 +163,9 @@ export default function Page() {
                         current={usage.overall.current}
                         isPaying={currentPlan?.v3Subscription?.isPaying ?? false}
                         tierLimit={
-                          isCurrentMonth
-                            ? (currentPlan?.v3Subscription?.plan?.limits.includedUsage ?? 0) / 100
-                            : undefined
+                          isCurrentMonth ? planLimitCents / 100 : undefined
                         }
+                        billingLimit={billingLimitDollars}
                       />
                     </div>
                   )}