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

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

* fix(billing): re-arm limit-notification dedup on usage drops (prior-usage + decrement)

* fix(billing): isolate per-admin email failures in org limit notifications

* fix(billing): re-arm limit dedup at zero usage and zero prior usage (full clear / wipe-rebuild)

* fix(billing): make storage-decrement notification re-arm only (never send on a shrink)

* fix(billing): resolve recipients before claiming so opt-outs don't burn the dedup threshold

* fix(billing): fire table limit emails on upsert inserts via shared notifyTableRowUsage

* chore(billing): only log a limit email as sent when a recipient actually received it

* chore(billing): match to_jsonb int cast between claim and re-arm for consistency

* fix(billing): notify table limits post-commit so a rolled-back insert never emails or burns the claim

* feat(pi): swap Pi Coding Agent icon to the pi glyph and use a black bgColor

* fix(billing): drop priorUsage re-arm to make dedup a single atomic claim (no duplicate-email race)

* docs(billing): move limit-notification rationale to TSDoc, correct tables warn-once behavior

* docs(db): note limit_notifications dedup is per-account, not per-table

* perf(billing): cut redundant subscription fetches and edge-gate notify to slash DB load

* docs(billing): drop self-explanatory inline comments from the notification path

Author: waleedlatif1

apps/docs/components/icons.tsx

@@ -5318,6 +5318,18 @@ export function SmtpIcon(props: SVGProps<SVGSVGElement>) {
   )
 }
 
+export function PiIcon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg {...props} xmlns='http://www.w3.org/2000/svg' viewBox='0 0 800 800' fill='currentColor'>
+      <path
+        fillRule='evenodd'
+        d='M165.29 165.29 H517.36 V400 H400 V517.36 H282.65 V634.72 H165.29 Z M282.65 282.65 V400 H400 V282.65 Z'
+      />
+      <path d='M517.36 400 H634.72 V634.72 H517.36 Z' />
+    </svg>
+  )
+}
+
 export function SshIcon(props: SVGProps<SVGSVGElement>) {
   return (
     <svg

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/blocks/blocks/pi.ts

@@ -53,7 +53,7 @@ export const PiBlock: BlockConfig<PiResponse> = {
   `,
   category: 'blocks',
   integrationType: IntegrationType.AI,
-  bgColor: '#6E56CF',
+  bgColor: '#000000',
   icon: PiIcon,
   subBlocks: [
     {