feat(usage): show a paid organisation that it is over its plan limit

Adds the banner and the line under the meter. The day the limit was
passed is worked out from the daily rows the page already holds, so
nothing new is fetched.

Restriction only ever applies to a free plan, so a paid organisation
over its limit keeps serving flags and the page reports the overage
alone. Whether that overage is charged or covered by the grace period
is #8264, which needs the API to say so, so the wording hedges until
then.

The global quota banner is hidden on this route. It says the same
thing without the figures, so on this page it would only repeat what
the page already shows.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: talissoncosta

frontend/documentation/components/UsageDashboard.stories.tsx

@@ -4,6 +4,7 @@ import { UsageDashboard } from 'components/pages/usage'
 import UsageBreakdown, {
   useUsageBreakdown,
 } from 'components/pages/usage/components/UsageBreakdown'
+import { overLimitNote, overLimitOf } from 'components/pages/usage/overLimit'
 import {
   allowanceWindow,
   contributionNote,
@@ -99,10 +100,20 @@ const UsagePage: FC<HarnessProps> = ({
     scenarioFor(billingPeriod, !!empty, isFreePlan),
     share * scale,
   )
-  const allowanceTotal = toUsageResponse(
+  const allowance = toUsageResponse(
     scenarioFor(allowanceWindow(basis), !!empty, isFreePlan),
     scale,
-  ).totals.total
+  )
+  const allowanceTotal = allowance.totals.total
+  const exceeded = overLimitOf(allowanceTotal, limit, allowance)
+
+  const contribution = showsContribution(
+    basis,
+    billingPeriod,
+    filtered ? 1 : undefined,
+  )
+    ? contributionNote(project, scoped.totals.total, allowanceTotal)
+    : undefined
 
   // The note needs the organisation over the period on screen, not over the
   // allowance window, or a project can read as more than all of it.
@@ -147,12 +158,11 @@ const UsagePage: FC<HarnessProps> = ({
       isError={isError}
       isLoading={isLoading}
       limit={limit}
-      meterNote={
-        showsContribution(basis, billingPeriod, filtered ? 1 : undefined)
-          ? contributionNote(project, scoped.totals.total, allowanceTotal)
-          : undefined
-      }
+      meterNote={exceeded ? overLimitNote(exceeded) : contribution}
       onRetry={() => {}}
+      overLimit={
+        exceeded ? { basis, canUpgrade: true, over: exceeded } : undefined
+      }
       periodLabel={periodLabel(periods, billingPeriod)}
       planCopy={planSectionCopy(basis, limit)}
       showPlanCeiling={showsPlanCeiling(
@@ -183,6 +193,9 @@ export const PaidApproachingTheLimit: Story = {
   args: { limit: 1400000, subscription: billed },
 }
 
+// Over the limit on a paid plan. Flags keep being served, since restriction
+// only ever applies to a free plan, so the page reports the overage and says
+// the charge may follow.
 export const PaidOverTheLimit: Story = {
   args: { limit: 900000, subscription: billed },
 }

frontend/web/components/App.js

@@ -371,12 +371,17 @@ const App = class extends Component {
                     />
                     {user && (
                       <>
-                        <OrganisationLimit
-                          id={AccountStore.getOrganisation()?.id}
-                          organisationPlan={
-                            AccountStore.getOrganisation()?.subscription.plan
-                          }
-                        />
+                        {/* The usage page says the same thing with the
+                            figures to back it up, so the global banner would
+                            only repeat it. */}
+                        {!isUsagePage(pathname) && (
+                          <OrganisationLimit
+                            id={AccountStore.getOrganisation()?.id}
+                            organisationPlan={
+                              AccountStore.getOrganisation()?.subscription.plan
+                            }
+                          />
+                        )}
                         <div className='container announcement-container'>
                           <div>
                             <Announcement />

frontend/web/components/pages/usage/UsageDashboard.tsx

@@ -2,6 +2,9 @@ import { FC, ReactNode } from 'react'
 import { Res } from 'common/types/responses'
 import { PlanLimit } from 'components/shared/UsageBar/utils'
 import EmptyState from 'components/EmptyState'
+import OverLimitBanner, {
+  OverLimitBannerProps,
+} from './components/OverLimitBanner'
 import SectionHeading from './components/SectionHeading'
 import UsageMeter from './components/UsageMeter'
 import UsageOverTime from './components/UsageOverTime'
@@ -21,6 +24,8 @@ export type UsageDashboardProps = {
   onRetry?: () => void
   filters?: ReactNode
   breakdown?: ReactNode
+  /** Set when the organisation has used more than its plan allows. */
+  overLimit?: OverLimitBannerProps
 }
 
 const UsageDashboard: FC<UsageDashboardProps> = ({
@@ -34,6 +39,7 @@ const UsageDashboard: FC<UsageDashboardProps> = ({
   limit,
   meterNote,
   onRetry,
+  overLimit,
   periodLabel,
   planCopy,
   showPlanCeiling,
@@ -65,6 +71,8 @@ const UsageDashboard: FC<UsageDashboardProps> = ({
   } else {
     content = (
       <>
+        {overLimit && <OverLimitBanner {...overLimit} />}
+
         <SectionHeading title={planCopy.title} hint={planCopy.hint} />
 
         <UsageMeter total={total} limit={limit} note={meterNote} />

frontend/web/components/pages/usage/UsageDashboardPage.tsx

@@ -8,6 +8,7 @@ import { PeriodOption } from 'common/types/requests'
 import UsageBreakdown, { useUsageBreakdown } from './components/UsageBreakdown'
 import UsageDashboard from './UsageDashboard'
 import { useUsageData } from './useUsageData'
+import { overLimitNote, overLimitOf } from './overLimit'
 import {
   isBilledOnAPeriod,
   isBillingPeriodSelected,
@@ -68,6 +69,10 @@ const UsageDashboardPage: FC<UsageDashboardPageProps> = ({
     organisationId ? { id: organisationId } : skipToken,
   )
 
+  const limit = subscriptionMeta?.max_api_calls
+  const allowanceTotal = usage.allowance?.totals?.total ?? 0
+  const exceeded = overLimitOf(allowanceTotal, limit, usage.allowance)
+
   const periods = periodsFor(planIsBilled)
 
   const { setDimension, ...breakdown } = useUsageBreakdown({
@@ -81,29 +86,33 @@ const UsageDashboardPage: FC<UsageDashboardPageProps> = ({
     .filter(Boolean)
     .join(' · ')
 
+  const contribution =
+    showsContribution(basis, billingPeriod, selectedProjectId) && projectName
+      ? contributionNote(
+          projectName,
+          usage.scoped?.totals?.total ?? 0,
+          allowanceTotal,
+        )
+      : undefined
+
+  // Being over the limit outranks the project's share of usage: the slot holds
+  // one line and only one of them is urgent.
+  const meterNote = exceeded ? overLimitNote(exceeded) : contribution
+
   if (!organisationId) {
     return null
   }
 
   return (
     <UsageDashboard
       data={usage.scoped}
-      total={usage.allowanceTotal}
-      limit={subscriptionMeta?.max_api_calls}
+      total={allowanceTotal}
+      limit={limit}
       hasBillingPeriod={isBillingPeriodSelected(billingPeriod)}
-      planCopy={planSectionCopy(basis, subscriptionMeta?.max_api_calls)}
+      planCopy={planSectionCopy(basis, limit)}
       periodLabel={periodLabel(periods, billingPeriod)}
       showPlanCeiling={showsPlanCeiling(billingPeriod, selectedProjectId)}
-      meterNote={
-        showsContribution(basis, billingPeriod, selectedProjectId) &&
-        projectName
-          ? contributionNote(
-              projectName,
-              usage.scoped?.totals?.total ?? 0,
-              usage.allowanceTotal,
-            )
-          : undefined
-      }
+      meterNote={meterNote}
       breakdown={
         <UsageBreakdown
           {...breakdown}
@@ -114,6 +123,17 @@ const UsageDashboardPage: FC<UsageDashboardPageProps> = ({
       isError={organisationFailed || usage.failed || limitFailed}
       isLoading={loadingOrganisation || usage.isLoadingPlan || loadingLimit}
       isExploring={usage.isLoadingScoped}
+      // Restriction only ever applies to a free plan, so a paid organisation
+      // over its limit keeps serving flags and this only reports the overage.
+      overLimit={
+        exceeded
+          ? {
+              basis,
+              canUpgrade: Utils.getFlagsmithHasFeature('payments_enabled'),
+              over: exceeded,
+            }
+          : undefined
+      }
       onRetry={() => {
         refetchOrganisation()
         refetchLimit()

frontend/web/components/pages/usage/__tests__/overLimit.test.ts

@@ -0,0 +1,115 @@
+import {
+  limitCrossedOn,
+  OverLimit,
+  overLimitBannerCopy,
+  overLimitNote,
+  overLimitOf,
+} from 'components/pages/usage/overLimit'
+import { UsageBasis } from 'components/pages/usage/utils'
+import { usageEvent, usageResponse } from './fixtures'
+
+const billed: UsageBasis = { window: 'billing-period' }
+
+const days = (perDay: number[]) =>
+  usageResponse(
+    perDay.map((flags, index) =>
+      usageEvent({ day: `2026-08-${`${index + 1}`.padStart(2, '0')}`, flags }),
+    ),
+  )
+
+// overLimitOf is undefined below the limit; every copy test is above it.
+const exceeding = (
+  total: number,
+  limit: number,
+  data?: ReturnType<typeof days>,
+) => overLimitOf(total, limit, data) as OverLimit
+
+describe('overLimit', () => {
+  describe('overLimitOf', () => {
+    it('is nothing until usage passes the limit', () => {
+      expect(overLimitOf(50000, 50000, days([50000]))).toBeUndefined()
+      expect(overLimitOf(49999, 50000, days([49999]))).toBeUndefined()
+    })
+
+    it('is nothing when the plan has no limit to pass', () => {
+      expect(overLimitOf(9999999, null, days([9999999]))).toBeUndefined()
+    })
+
+    it('reports how far over, and carries the limit it is over', () => {
+      const over = overLimitOf(60000, 50000, days([60000]))
+
+      expect(over?.overBy).toBe(10000)
+      expect(over?.limit).toBe(50000)
+    })
+  })
+
+  describe('limitCrossedOn', () => {
+    it('names the day the running total reached the limit', () => {
+      expect(limitCrossedOn(days([40, 40, 40, 40]), 100)).toBe('3 Aug')
+    })
+
+    // The API returns a row per day per user agent, so a day only counts once
+    // its rows are added together.
+    it('adds up the rows a day is split across', () => {
+      const data = usageResponse([
+        usageEvent({ day: '2026-08-01', flags: 60 }),
+        usageEvent({ day: '2026-08-01', identities: 60 }),
+        usageEvent({ day: '2026-08-02', flags: 10 }),
+      ])
+
+      expect(limitCrossedOn(data, 100)).toBe('1 Aug')
+    })
+
+    it('reads the days in order, whatever order they arrive in', () => {
+      const data = usageResponse([
+        usageEvent({ day: '2026-08-03', flags: 40 }),
+        usageEvent({ day: '2026-08-01', flags: 40 }),
+        usageEvent({ day: '2026-08-02', flags: 40 }),
+      ])
+
+      expect(limitCrossedOn(data, 100)).toBe('3 Aug')
+    })
+
+    it('says nothing when the days never reach the limit', () => {
+      expect(limitCrossedOn(days([10, 10]), 100)).toBeUndefined()
+      expect(limitCrossedOn(undefined, 100)).toBeUndefined()
+    })
+  })
+
+  describe('copy', () => {
+    it('names the day when the data shows it', () => {
+      const over = exceeding(60000, 50000, days([40000, 20000]))
+
+      expect(overLimitBannerCopy(over, billed).body).toContain(
+        'plan limit on 2 Aug',
+      )
+    })
+
+    // Defensive: the totals and the daily rows come from one response, so a
+    // total over the limit normally has a crossing day somewhere in the rows.
+    it('leaves the day out when the rows are missing', () => {
+      const over = exceeding(60000, 50000)
+
+      expect(overLimitBannerCopy(over, billed).body).toContain(
+        'plan limit. Overage',
+      )
+    })
+
+    it('measures the overage over the window the meter shows', () => {
+      const over = exceeding(60000, 50000, days([60000]))
+
+      expect(overLimitBannerCopy(over, billed).body).toContain(
+        'this billing period',
+      )
+      expect(
+        overLimitBannerCopy(over, { window: 'rolling' } as UsageBasis).body,
+      ).toContain('the last 30 days')
+    })
+
+    it('says how far over in the note under the meter', () => {
+      const over = exceeding(60000, 50000, days([60000]))
+
+      expect(overLimitNote(over)).toBe('10K calls over your 50K limit.')
+    })
+  })
+})

frontend/web/components/pages/usage/components/OverLimitBanner/OverLimitBanner.tsx

@@ -0,0 +1,43 @@
+import { FC } from 'react'
+import Constants from 'common/constants'
+import { Button } from 'components/base/forms/Button'
+import Icon from 'components/icons/Icon'
+import {
+  overLimitBannerCopy,
+  OverLimit,
+} from 'components/pages/usage/overLimit'
+import { UsageBasis } from 'components/pages/usage/utils'
+
+export type OverLimitBannerProps = {
+  over: OverLimit
+  basis: UsageBasis
+  canUpgrade?: boolean
+}
+
+const OverLimitBanner: FC<OverLimitBannerProps> = ({
+  basis,
+  canUpgrade,
+  over,
+}) => {
+  const { body, title } = overLimitBannerCopy(over, basis)
+
+  return (
+    <div className='alert alert-danger d-flex align-items-start gap-3 mb-4'>
+      <Icon name='close-circle' />
+      <div className='flex-fill'>
+        <strong className='d-block'>{title}</strong>
+        {body}
+      </div>
+      {canUpgrade && (
+        <Button
+          className='flex-shrink-0'
+          href={Constants.getUpgradeUrl('usage')}
+        >
+          Upgrade plan
+        </Button>
+      )}
+    </div>
+  )
+}
+
+export default OverLimitBanner

frontend/web/components/pages/usage/components/OverLimitBanner/index.ts

@@ -0,0 +1,2 @@
+export { default } from './OverLimitBanner'
+export type { OverLimitBannerProps } from './OverLimitBanner'