feat(billing): unify upgrade routing with reason context + storage/tables limit emails

Author: waleedlatif1

apps/sim/app/workspace/[workspaceId]/files/files.tsx

@@ -2,7 +2,7 @@
 
 import { type DragEvent, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { createLogger } from '@sim/logger'
-import { toError } from '@sim/utils/errors'
+import { getErrorMessage, toError } from '@sim/utils/errors'
 import { useParams, useRouter } from 'next/navigation'
 import { useQueryStates } from 'nuqs'
 import { usePostHog } from 'posthog-js/react'
@@ -25,6 +25,7 @@ import {
 } from '@/components/emcn'
 import { Download, Send } from '@/components/emcn/icons'
 import { getDocumentIcon } from '@/components/icons/document-icons'
+import { useLimitUpgradeToast } from '@/lib/billing/client'
 import { captureEvent } from '@/lib/posthog/client'
 import { triggerFileDownload } from '@/lib/uploads/client/download'
 import type { WorkspaceFileRecord } from '@/lib/uploads/contexts/workspace'
@@ -197,6 +198,7 @@ export function Files() {
   const { data: folders = EMPTY_WORKSPACE_FILE_FOLDERS } = useWorkspaceFileFolders(workspaceId)
   const { data: members } = useWorkspaceMembersQuery(workspaceId)
   const uploadFile = useUploadWorkspaceFile()
+  const notifyLimit = useLimitUpgradeToast()
   const deleteFile = useDeleteWorkspaceFile()
   const renameFile = useRenameWorkspaceFile()
   const createFolder = useCreateWorkspaceFileFolder()
@@ -699,6 +701,12 @@ export function Files() {
             })
           } catch (err) {
             logger.error('Error uploading file:', err)
+            const message = getErrorMessage(err)
+            if (/storage limit/i.test(message)) {
+              notifyLimit('storage', message)
+            } else {
+              toast.error(`Failed to upload "${allowedFiles[i].name}"`)
+            }
           }
         }
       } catch (err) {
@@ -708,7 +716,7 @@ export function Files() {
         setUploadProgress({ completed: 0, total: 0, currentPercent: 0 })
       }
     },
-    [workspaceId, canEdit, currentFolderId]
+    [workspaceId, canEdit, currentFolderId, notifyLimit]
   )
 
   const rowDragDropConfig = useMemo<RowDragDropConfig>(

apps/sim/app/workspace/[workspaceId]/home/components/credits-chip/credits-chip.tsx

@@ -7,6 +7,7 @@ import { Chip } from '@/components/emcn'
 import { Credit } from '@/components/emcn/icons'
 import { ON_DEMAND_UNLIMITED } from '@/lib/billing/constants'
 import { formatCredits } from '@/lib/billing/credits/conversion'
+import { buildUpgradeHref } from '@/lib/billing/upgrade-reasons'
 import { isBillingEnabled } from '@/app/workspace/[workspaceId]/settings/navigation'
 import { useMyMemberCredits } from '@/hooks/queries/organization'
 import { usePlanView } from '@/hooks/queries/plan-view'
@@ -33,7 +34,7 @@ function CreditsChipInner() {
   const { workspaceId } = useParams<{ workspaceId: string }>()
   const { data: memberCredits, isLoading: memberLoading } = useMyMemberCredits(workspaceId)
 
-  const upgradeHref = `/workspace/${workspaceId}/upgrade`
+  const upgradeHref = buildUpgradeHref(workspaceId, 'credits')
 
   /**
    * Warm the route bundle and the exact queries the Upgrade page gates on, so

apps/sim/app/workspace/[workspaceId]/settings/components/billing/billing.tsx

@@ -33,6 +33,7 @@ import {
   hasPaidSubscriptionStatus,
   hasUsableSubscriptionAccess,
 } from '@/lib/billing/subscriptions/utils'
+import { buildUpgradeHref } from '@/lib/billing/upgrade-reasons'
 import { cn } from '@/lib/core/utils/cn'
 import { getBaseUrl } from '@/lib/core/utils/urls'
 import { UsageLimitField } from '@/app/workspace/[workspaceId]/settings/components/billing/components/usage-limit-field/usage-limit-field'
@@ -125,7 +126,7 @@ export function Billing() {
   const betterAuthSubscription = useSubscription()
   const openBillingPortal = useOpenBillingPortal()
 
-  const upgradeHref = `/workspace/${workspaceId}/upgrade`
+  const upgradeHref = buildUpgradeHref(workspaceId)
 
   /**
    * Warm the Upgrade route bundle and the exact queries that page gates on, so

apps/sim/app/workspace/[workspaceId]/settings/components/teammates/teammates.tsx

@@ -24,6 +24,7 @@ import {
   workspaceRoleLockReason,
 } from '@/components/permissions'
 import type { WorkspacePermission } from '@/lib/api/contracts/workspaces'
+import { buildUpgradeHref } from '@/lib/billing/upgrade-reasons'
 import {
   MemberRow,
   MemberSection,
@@ -105,7 +106,7 @@ export function Teammates() {
   const inviteDisabledReason = activeWorkspace?.inviteDisabledReason ?? null
   const isInvitationsDisabled = isInvitationsDisabledByConfig || inviteDisabledReason !== null
 
-  const upgradeHref = `/workspace/${workspaceId}/upgrade`
+  const upgradeHref = buildUpgradeHref(workspaceId, 'seats')
 
   /**
    * Warm the Upgrade route bundle and the queries it gates on, so a gated

apps/sim/app/workspace/[workspaceId]/upgrade/page.tsx

@@ -1,3 +1,4 @@
+import { Suspense } from 'react'
 import type { Metadata } from 'next'
 import { Upgrade } from '@/app/workspace/[workspaceId]/upgrade/upgrade'
 
@@ -9,5 +10,9 @@ export default async function UpgradePage({
   params: Promise<{ workspaceId: string }>
 }) {
   const { workspaceId } = await params
-  return <Upgrade workspaceId={workspaceId} />
+  return (
+    <Suspense fallback={<div className='h-full bg-[var(--bg)]' />}>
+      <Upgrade workspaceId={workspaceId} />
+    </Suspense>
+  )
 }

apps/sim/app/workspace/[workspaceId]/upgrade/search-params.ts

@@ -0,0 +1,20 @@
+import { parseAsStringLiteral } from 'nuqs/server'
+import { UPGRADE_REASONS } from '@/lib/billing/upgrade-reasons'
+
+/**
+ * Single source of truth for the upgrade page's `reason` query param.
+ *
+ * Nullable (no `.withDefault`): a clean URL means no reason and the page keeps
+ * its generic header. Shared by the client (`useQueryState`) and any server
+ * read via `createSearchParamsCache`.
+ */
+export const upgradeReasonParam = {
+  key: 'reason',
+  parser: parseAsStringLiteral(UPGRADE_REASONS),
+} as const
+
+/** Clean URLs, no back-stack churn — the reason is a passive header hint. */
+export const upgradeUrlKeys = {
+  history: 'replace',
+  clearOnDefault: true,
+} as const

apps/sim/app/workspace/[workspaceId]/upgrade/upgrade.tsx

@@ -3,6 +3,7 @@
 import { useCallback, useEffect, useState } from 'react'
 import { getErrorMessage } from '@sim/utils/errors'
 import { useRouter } from 'next/navigation'
+import { useQueryState } from 'nuqs'
 import { ArrowLeft, Chip, toast } from '@/components/emcn'
 import {
   getUpgradeCardCta,
@@ -11,6 +12,7 @@ import {
   type UpgradeCardId,
 } from '@/lib/billing/client'
 import { ANNUAL_DISCOUNT_RATE } from '@/lib/billing/constants'
+import { DEFAULT_UPGRADE_HEADER, UPGRADE_REASON_COPY } from '@/lib/billing/upgrade-reasons'
 import { isBillingEnabled } from '@/app/workspace/[workspaceId]/settings/navigation'
 import {
   BillingPeriodToggle,
@@ -26,6 +28,10 @@ import {
   PRO_PLAN_CREDITS,
   PRO_PLAN_FEATURES,
 } from '@/app/workspace/[workspaceId]/upgrade/plan-configs'
+import {
+  upgradeReasonParam,
+  upgradeUrlKeys,
+} from '@/app/workspace/[workspaceId]/upgrade/search-params'
 import { useFullscreenOriginStore } from '@/stores/fullscreen-origin'
 
 const TYPEFORM_ENTERPRISE_URL = 'https://form.typeform.com/to/jqCO12pF' as const
@@ -47,8 +53,14 @@ export function Upgrade({ workspaceId }: UpgradeProps) {
   const state = useUpgradeState()
   const router = useRouter()
   const origin = useFullscreenOriginStore((s) => s.origin)
+  const [reason] = useQueryState(upgradeReasonParam.key, {
+    ...upgradeReasonParam.parser,
+    ...upgradeUrlKeys,
+  })
   const [showAllFeatures, setShowAllFeatures] = useState(false)
 
+  const header = reason ? UPGRADE_REASON_COPY[reason].header : DEFAULT_UPGRADE_HEADER
+
   const handleBack = useCallback(() => {
     router.replace(origin ?? `/workspace/${workspaceId}/home`)
   }, [origin, router, workspaceId])
@@ -152,7 +164,7 @@ export function Upgrade({ workspaceId }: UpgradeProps) {
         <div className='mx-auto flex w-full max-w-[960px] flex-col gap-7 pt-6 pb-3'>
           <div className='flex flex-col items-center gap-4'>
             <h1 className='text-balance text-center font-season text-[30px] text-[var(--text-primary)]'>
-              Plans that scale with you
+              {header}
             </h1>
             {state.showUpgradePlans && (
               <BillingPeriodToggle isAnnual={state.isAnnual} onChange={state.setIsAnnual} />

apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/deploy/components/deploy-modal/components/deploy-upgrade-gate/deploy-upgrade-gate.tsx

@@ -4,6 +4,7 @@ import { useQueryClient } from '@tanstack/react-query'
 import { ArrowRight } from 'lucide-react'
 import { useParams, useRouter } from 'next/navigation'
 import { ChipLink } from '@/components/emcn'
+import { buildUpgradeHref } from '@/lib/billing/upgrade-reasons'
 import { prefetchUpgradeBillingData } from '@/hooks/queries/subscription'
 import { prefetchWorkspaceSettings } from '@/hooks/queries/workspace'
 
@@ -15,7 +16,7 @@ export function DeployUpgradeGate({ feature }: DeployUpgradeGateProps) {
   const router = useRouter()
   const queryClient = useQueryClient()
   const { workspaceId } = useParams<{ workspaceId: string }>()
-  const upgradeHref = `/workspace/${workspaceId}/upgrade`
+  const upgradeHref = buildUpgradeHref(workspaceId)
 
   // Warm the upgrade route + the queries it gates on so the click lands on
   // cached data. ChipLink isn't memoized, so no useCallback is needed.

apps/sim/components/emails/billing/index.ts

@@ -3,6 +3,7 @@ export { CreditPurchaseEmail } from './credit-purchase-email'
 export { CreditsExhaustedEmail } from './credits-exhausted-email'
 export { EnterpriseSubscriptionEmail } from './enterprise-subscription-email'
 export { FreeTierUpgradeEmail } from './free-tier-upgrade-email'
+export { LimitThresholdEmail } from './limit-threshold-email'
 export { PaymentFailedEmail } from './payment-failed-email'
 export { PlanWelcomeEmail } from './plan-welcome-email'
 export { UsageThresholdEmail } from './usage-threshold-email'

apps/sim/components/emails/billing/limit-threshold-email.tsx

@@ -0,0 +1,76 @@
+import { Link, Section, Text } from '@react-email/components'
+import { baseStyles } from '@/components/emails/_styles'
+import { EmailLayout } from '@/components/emails/components'
+import { UPGRADE_REASON_COPY, type UpgradeReason } from '@/lib/billing/upgrade-reasons'
+import { getBrandConfig } from '@/ee/whitelabeling'
+
+interface LimitThresholdEmailProps {
+  /** `warning` = approaching the limit (~80%); `reached` = at/over the limit. */
+  kind: 'warning' | 'reached'
+  /** Limit category, drives the shared copy. */
+  reason: UpgradeReason
+  userName?: string
+  /** Pre-formatted current usage, e.g. "4.2 GB", "48,000 rows", "9 seats". */
+  usageLabel: string
+  /** Pre-formatted limit, e.g. "5 GB", "50,000 rows", "10 seats". */
+  limitLabel: string
+  percentUsed: number
+  upgradeLink: string
+}
+
+/**
+ * Single template for the per-category usage-limit emails (storage, tables,
+ * seats). Copy comes from {@link UPGRADE_REASON_COPY} so the email language
+ * matches the upgrade-page header the user lands on.
+ */
+export function LimitThresholdEmail({
+  kind,
+  reason,
+  userName,
+  usageLabel,
+  limitLabel,
+  percentUsed,
+  upgradeLink,
+}: LimitThresholdEmailProps) {
+  const brand = getBrandConfig()
+  const copy = UPGRADE_REASON_COPY[reason]
+  const lead = kind === 'reached' ? copy.reachedLead : copy.warningLead
+  const previewText = `${brand.name}: ${lead}`
+
+  return (
+    <EmailLayout preview={previewText} showUnsubscribe={true}>
+      <Text style={{ ...baseStyles.paragraph, marginTop: 0 }}>
+        {userName ? `Hi ${userName},` : 'Hi,'}
+      </Text>
+
+      <Text style={baseStyles.paragraph}>
+        {lead} Upgrade your plan for more {copy.noun}.
+      </Text>
+
+      <Section style={baseStyles.infoBox}>
+        <Text style={baseStyles.infoBoxTitle}>Usage</Text>
+        <Text style={baseStyles.infoBoxList}>
+          {usageLabel} of {limitLabel} used ({percentUsed}%)
+        </Text>
+      </Section>
+
+      {/* Divider */}
+      <div style={baseStyles.divider} />
+
+      <Link href={upgradeLink} style={{ textDecoration: 'none' }}>
+        <Text style={baseStyles.button}>Upgrade</Text>
+      </Link>
+
+      {/* Divider */}
+      <div style={baseStyles.divider} />
+
+      <Text style={{ ...baseStyles.footerText, textAlign: 'left' }}>
+        {kind === 'reached'
+          ? 'One-time notification at 100% usage.'
+          : 'One-time notification at 80% usage.'}
+      </Text>
+    </EmailLayout>
+  )
+}
+
+export default LimitThresholdEmail