Flagsmith · talissoncosta · Aug 25, 2026 · Aug 25, 2026 · Aug 25, 2026 · Aug 25, 2026
@@ -9,19 +9,27 @@ export type UsageDashboardProps = {
   data: Res['organisationUsage'] | undefined
   total: number
   limit: PlanLimit
+  comparable?: boolean
+  showPlanCeiling?: boolean
+  projectName?: string
   hasBillingPeriod: boolean
   isError?: boolean
   isLoading?: boolean
+  onRetry?: () => void
   filters?: ReactNode
 }
 
 const UsageDashboard: FC<UsageDashboardProps> = ({
+  comparable,
   data,
   filters,
   hasBillingPeriod,
   isError,
   isLoading,
   limit,
+  onRetry,
+  projectName,
+  showPlanCeiling,
   total,
 }) => {
   let content
@@ -38,16 +46,28 @@ const UsageDashboard: FC<UsageDashboardProps> = ({
         title='Usage could not be loaded'
         description='Something went wrong fetching usage for this period. Try again in a moment.'
         icon='bar-chart'
+        action={
+          onRetry && (
+            <Button onClick={onRetry} theme='secondary'>
+              Try again
+            </Button>
+          )
+        }
       />
     )
   } else {
     content = (
       <>
-        <UsageMeter total={total} limit={limit} />
+        <UsageMeter
+          total={total}
+          limit={limit}
+          comparable={comparable}
+          projectName={projectName}
+        />
 
         <UsageOverTime
           data={data}
-          limit={limit}
+          limit={showPlanCeiling ? limit : undefined}
           isBillingPeriod={hasBillingPeriod}
         />
       </>

@@ -10,6 +10,8 @@ import { PeriodOption } from 'common/types/requests'
 import UsageDashboard from './UsageDashboard'
 import {
   isBillingPeriodSelected,
+  isComparableToAllowance,
+  showsPlanCeiling,
   periodsFor,
   PeriodSelection,
   planHasBillingPeriod,
@@ -25,11 +27,14 @@ const UsageDashboardPage: FC<UsageDashboardPageProps> = ({
   organisationId,
 }) => {
   const [project, setProject] = useState<string | undefined>()
+  const [projectName, setProjectName] = useState<string | undefined>()
+  const selectedProjectId = project ? Number(project) : undefined
 
   const {
     data: organisation,
     isError: organisationFailed,
     isLoading: loadingOrganisation,
+    refetch: refetchOrganisation,
   } = useGetOrganisationQuery(
     organisationId ? { id: organisationId } : skipToken,
   )
@@ -45,19 +50,24 @@ const UsageDashboardPage: FC<UsageDashboardPageProps> = ({
     data,
     isError: usageFailed,
     isFetching: loadingUsage,
+    isUninitialized: usageNotStarted,
+    refetch: refetchUsage,
   } = useGetOrganisationUsageQuery(
     organisationId && organisation
       ? {
           billing_period: billingPeriod,
           organisationId,
-          projectId: project ? Number(project) : undefined,
+          projectId: selectedProjectId,
         }
       : skipToken,
   )
-  const { data: subscriptionMeta, isLoading: loadingLimit } =
-    useGetSubscriptionMetadataQuery(
-      organisationId ? { id: organisationId } : skipToken,
-    )
+  const {
+    data: subscriptionMeta,
+    isLoading: loadingLimit,
+    refetch: refetchLimit,
+  } = useGetSubscriptionMetadataQuery(
+    organisationId ? { id: organisationId } : skipToken,
+  )
 
   const periods = periodsFor(planIsBilled)
 
@@ -71,8 +81,18 @@ const UsageDashboardPage: FC<UsageDashboardPageProps> = ({
       total={data?.totals?.total ?? 0}
       limit={subscriptionMeta?.max_api_calls}
       hasBillingPeriod={isBillingPeriodSelected(billingPeriod)}
+      comparable={isComparableToAllowance(billingPeriod)}
+      showPlanCeiling={showsPlanCeiling(billingPeriod, selectedProjectId)}
+      projectName={selectedProjectId ? projectName : undefined}
       isError={organisationFailed || usageFailed}
       isLoading={loadingOrganisation || loadingUsage || loadingLimit}
+      onRetry={() => {
+        refetchOrganisation()
+        refetchLimit()
+        if (!usageNotStarted) {
+          refetchUsage()
+        }
+      }}
       filters={
         <Row className='gap-3 align-items-end'>
           <div className='usage-dashboard__filter'>
@@ -90,7 +110,10 @@ const UsageDashboardPage: FC<UsageDashboardPageProps> = ({
               inputId='usage-project'
               showAll
               organisationId={organisationId}
-              onChange={setProject}
+              onChange={(id: string, name: string) => {
+                setProject(id)
+                setProjectName(name)
+              }}
               value={project}
             />
           </div>

@@ -1,5 +1,7 @@
 import { Subscription } from 'common/types/responses'
 import {
+  isComparableToAllowance,
+  showsPlanCeiling,
   isBillingPeriodSelected,
   planHasBillingPeriod,
   periodsFor,
@@ -81,6 +83,33 @@ describe('UsageDashboard utils', () => {
     })
   })
 
+  describe('isComparableToAllowance', () => {
+    it('compares the 30 day window and the billing periods', () => {
+      expect(isComparableToAllowance(undefined)).toBe(true)
+      expect(isComparableToAllowance('current_billing_period')).toBe(true)
+    })
+
+    it('refuses the 90 day window against a 30 day allowance', () => {
+      expect(isComparableToAllowance('90_day_period')).toBe(false)
+    })
+  })
+
+  describe('showsPlanCeiling', () => {
+    it('draws the ceiling for the organisation over a comparable period', () => {
+      expect(showsPlanCeiling(undefined, undefined)).toBe(true)
+      expect(showsPlanCeiling('current_billing_period', undefined)).toBe(true)
+    })
+
+    it('drops it for one project, which will never reach the ceiling', () => {
+      expect(showsPlanCeiling(undefined, 12)).toBe(false)
+      expect(showsPlanCeiling('current_billing_period', 12)).toBe(false)
+    })
+
+    it('drops it for the 90 day window', () => {
+      expect(showsPlanCeiling('90_day_period', undefined)).toBe(false)
+    })
+  })
+
   describe('periodsFor', () => {
     it('offers the billing periods only when there is a term', () => {
       expect(periodsFor(true).map((period) => period.value)).toContain(

@@ -1,12 +1,7 @@
 import { FC, ReactNode } from 'react'
-import Format from 'common/utils/format'
 import UsageBar from 'components/shared/UsageBar'
-import {
-  PlanLimit,
-  toneFor,
-  usagePercent,
-} from 'components/shared/UsageBar/utils'
-import { meterCopy } from './utils'
+import { PlanLimit } from 'components/shared/UsageBar/utils'
+import { meterCopy, meterTone } from './utils'
 import './UsageMeter.scss'
 
 const WARN_AT = 75
@@ -15,39 +10,53 @@ const NOTIFICATION_THRESHOLDS = [WARN_AT, 100]
 export type UsageMeterProps = {
   total: number
   limit: PlanLimit
+  comparable?: boolean
+  projectName?: string
   note?: ReactNode
 }
 
-const UsageMeter: FC<UsageMeterProps> = ({ limit, note, total }) => {
-  const copy = meterCopy(total, limit)
-  const tone = toneFor(usagePercent(total, limit), WARN_AT)
+const UsageMeter: FC<UsageMeterProps> = ({
+  comparable = true,
+  limit,
+  note,
+  projectName,
+  total,
+}) => {
+  const copy = meterCopy(total, limit, comparable, projectName)
+  const tone = meterTone(total, limit, comparable, WARN_AT)
 
   return (
     <div className='p-4 mb-3 border border-default rounded-lg bg-surface-default'>
       <div className='d-flex align-items-end justify-content-between gap-3 mb-4'>
         <div>
-          <p className='fs-caption text-secondary mb-1'>Plan usage</p>
+          <p className='fs-caption text-secondary mb-1'>{copy.label}</p>
           <div className='d-flex align-items-end gap-2'>
-            <span className={`usage-meter__percent fw-bold lh-1 text-${tone}`}>
+            <span
+              className={`usage-meter__percent fw-bold lh-1 ${
+                tone ? `text-${tone}` : ''
+              }`}
+            >
               {copy.headline}
             </span>
             <span className='fs-captionSmall text-secondary'>
               {copy.headlineCaption}
             </span>
           </div>
         </div>
-        <div className='usage-meter__fraction text-end'>
-          <div>
-            <strong>{Format.shortenNumber(total)}</strong>
-            {copy.fractionSuffix}
+        {copy.fraction && (
+          <div className='usage-meter__fraction text-end'>
+            <div>
+              <strong>{copy.fraction.value}</strong>
+              {copy.fraction.suffix}
+            </div>
+            <div className='fs-captionSmall text-secondary'>
+              {copy.fraction.caption}
+            </div>
           </div>
-          <div className='fs-captionSmall text-secondary'>
-            {copy.fractionCaption}
-          </div>
-        </div>
+        )}
       </div>
 
-      {!!limit && (
+      {!!limit && comparable && (
         <UsageBar
           usage={total}
           limit={limit}

@@ -1,13 +1,20 @@
-import { meterCopy } from 'components/pages/usage/components/UsageMeter/utils'
+import {
+  meterCopy,
+  meterTone,
+} from 'components/pages/usage/components/UsageMeter/utils'
 
 describe('UsageMeter utils', () => {
   describe('meterCopy', () => {
     it('reads as a percentage of the limit when there is one', () => {
       expect(meterCopy(1500000, 2000000)).toEqual({
-        fractionCaption: 'API calls used / plan limit',
-        fractionSuffix: ' / 2M',
+        fraction: {
+          caption: 'API calls used / plan limit',
+          suffix: ' / 2M',
+          value: '1.5M',
+        },
         headline: '75%',
         headlineCaption: 'of plan consumed',
+        label: 'Plan usage',
       })
     })
 
@@ -20,17 +27,57 @@ describe('UsageMeter utils', () => {
       'falls back to the raw count when the limit is %p',
       (limit) => {
         expect(meterCopy(1500000, limit)).toEqual({
-          fractionCaption: 'API calls used',
-          fractionSuffix: '',
+          fraction: undefined,
           headline: '1.5M',
           headlineCaption: 'API calls',
+          label: 'Plan usage',
         })
       },
     )
 
+    it('reports the count and names the allowance window when not comparable', () => {
+      expect(meterCopy(1500000, 2000000, false)).toEqual({
+        fraction: { caption: 'allowance per 30 days', value: '2M' },
+        headline: '1.5M',
+        headlineCaption: 'API calls',
+        label: 'Plan usage',
+      })
+    })
+
+    it('names the project and what the percentage is of when one is chosen', () => {
+      const copy = meterCopy(500000, 2000000, true, 'Checkout')
+
+      expect(copy.label).toBe('Plan usage · Checkout')
+      expect(copy.headline).toBe('25%')
+      expect(copy.headlineCaption).toBe('of your allowance')
+    })
+
+    it('keeps naming the project when the period rules the percentage out', () => {
+      const copy = meterCopy(500000, 2000000, false, 'Checkout')
+
+      expect(copy.label).toBe('Plan usage · Checkout')
+      expect(copy.headline).toBe('500K')
+    })
+
     it('shows zero rather than NaN for an organisation with no calls', () => {
       expect(meterCopy(0, null).headline).toBe('0')
       expect(meterCopy(0, 2000000).headline).toBe('0%')
     })
   })
+
+  describe('meterTone', () => {
+    it('tracks the thresholds when the comparison holds', () => {
+      expect(meterTone(500000, 2000000, true, 75)).toBe('success')
+      expect(meterTone(1600000, 2000000, true, 75)).toBe('warning')
+      expect(meterTone(2000000, 2000000, true, 75)).toBe('danger')
+    })
+
+    it('has no tone to give when the comparison does not hold', () => {
+      expect(meterTone(9000000, 2000000, false, 75)).toBeUndefined()
+    })
+
+    it('has no tone to give without a limit', () => {
+      expect(meterTone(9000000, null, true, 75)).toBeUndefined()
+    })
+  })
 })