fix(customers): align budget displays with recorded reset windows (#51658)

This commit is contained in:
tin-berri 2026-11-13 12:02:16 -08:00 • committed by GitHub
parent 45b726fdab
commit b34478b960
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
24 changed files with 1065 additions and 107 deletions

View file

@ -51,6 +51,7 @@ from litellm.repositories.verification_token_repository import (
)
if TYPE_CHECKING:
from prisma.models import LiteLLM_BudgetWindowSpend
from prisma.types import LiteLLM_EndUserTableWhereUniqueInput
from litellm.proxy.utils import PrismaClient
@ -78,6 +79,16 @@ def _as_utc(value: datetime) -> datetime:
return value if value.tzinfo is not None else value.replace(tzinfo=timezone.utc)
def recorded_window_spend(
row: "LiteLLM_BudgetWindowSpend | None", entity_type: str, expected_window_start: datetime | None
) -> float | None:
if expected_window_start is None:
return None
if row is None or _as_utc(row.window_start) < _as_utc(expected_window_start):
return 0.0 if entity_type.startswith("customer_") else None
return float(row.spend or 0.0)
_CUSTOMER_OVERRIDE_INCLUDE: Final = MappingProxyType({"budget": True, "budget_override": True})
_CUSTOMER_COUNTER: Final = re.compile(
r"spend:(customer_org|customer_team|customer_member):(.+):"
@ -369,11 +380,7 @@ class SpendCounterReseed:
)
return None
if row is None or _as_utc(row.window_start) < _as_utc(expected_window_start):
# Customer windows are new maintained balances, with no historical
# SpendLogs aggregate. A missing period starts at zero, a failed read above does not.
return 0.0 if entity_type.startswith("customer_") else None
return float(row.spend or 0.0)
return recorded_window_spend(row, entity_type, expected_window_start)
@staticmethod
async def window_from_db(

View file

@ -0,0 +1,103 @@
from collections.abc import Mapping, Sequence
from datetime import datetime
from itertools import chain
from typing import TYPE_CHECKING, Final, TypeVar
from litellm.proxy.common_utils.timezone_utils import BudgetResetSettings
from litellm.repositories.chunked_in import find_many_in
from litellm.repositories.prisma_protocols import TableActions
from litellm.types.proxy.auth.customer_hierarchy import CustomerScopeKey
from litellm.types.proxy.management_endpoints.customer_hierarchy import (
Budget,
CustomerBudgetUsage,
CustomerMember,
Organization,
Team,
)
if TYPE_CHECKING:
from prisma.models import LiteLLM_BudgetWindowSpend
from litellm.proxy.spend_tracking.budget_reservation import BudgetCounter
Entity: Final = TypeVar("Entity", Organization, Team, CustomerMember)
def _identity(entity: Organization | Team | CustomerMember) -> tuple[CustomerScopeKey, str, Budget | None]:
if isinstance(entity, Organization):
return "customer_org", entity.customer_org_id, entity.budget
if isinstance(entity, Team):
return "customer_team", entity.customer_team_id, entity.effective_budget
return "customer_member", entity.customer_member_id, entity.effective_budget
def _scalar_usage(
entity: Organization | Team | CustomerMember, budget: Budget | None
) -> tuple[CustomerBudgetUsage, ...]:
if budget is None or budget.max_budget is None:
return ()
return (
CustomerBudgetUsage(
source="scalar",
budget_duration=budget.budget_duration,
max_budget=budget.max_budget,
spend=entity.spend,
reset_at=entity.budget_reset_at,
),
)
def _usage(
counters: Sequence["BudgetCounter"],
rows: Mapping[tuple[str, str, str], "LiteLLM_BudgetWindowSpend"],
) -> tuple[CustomerBudgetUsage, ...]:
from litellm.proxy.db.spend_counter_reseed import recorded_window_spend
return tuple(
CustomerBudgetUsage(
source="window",
budget_duration=counter.window_duration,
max_budget=counter.max_budget,
spend=recorded_window_spend(
rows.get((counter.entity_type, counter.entity_id, counter.window_duration or "")),
counter.entity_type,
counter.window_start,
),
window_start=counter.window_start,
reset_at=counter.reset_at,
)
for counter in counters
)
async def customer_budget_usage(
entities: Sequence[Entity],
table: TableActions["LiteLLM_BudgetWindowSpend"],
now: datetime,
settings: BudgetResetSettings,
) -> tuple[Entity, ...]:
from litellm.proxy.spend_tracking.budget_reservation import customer_window_counters
if not entities:
return ()
identities: Final = tuple(_identity(entity) for entity in entities)
counters: Final = tuple(
customer_window_counters(scope, entity_id, budget.budget_limits or (), now=now, reset_settings=settings)
if budget is not None
else ()
for scope, entity_id, budget in identities
)
windows: Final = tuple(chain.from_iterable(counters))
rows: Final = await find_many_in(
table,
"entity_id",
tuple(counter.entity_id for counter in windows),
where={"entity_type": identities[0][0]},
)
by_window: Final = {(row.entity_type, row.entity_id, row.window_duration): row for row in rows}
return tuple(
entity.model_copy(
update={"budget_usage": _scalar_usage(entity, identity[2]) + _usage(entity_windows, by_window)}
)
for entity, identity, entity_windows in zip(entities, identities, counters, strict=True)
)

View file

@ -17,6 +17,7 @@ from litellm.proxy.common_utils.timezone_utils import (
)
from litellm.proxy.db.db_span import db_span
from litellm.proxy.list_api.common import escape_like
from litellm.proxy.management_helpers.customer_budget_usage import customer_budget_usage
from litellm.repositories.budget_repository import create_budget_row, update_budget_row
from litellm.repositories.chunked_in import delete_many_in, find_many_in
from litellm.repositories.prisma_protocols import TableActions
@ -38,6 +39,7 @@ from litellm.types.proxy.management_endpoints.customer_hierarchy import (
if TYPE_CHECKING:
from prisma import Json, Prisma
from prisma.models import LiteLLM_BudgetWindowSpend
class ErrorCode(str, Enum):
@ -472,6 +474,7 @@ class CustomerHierarchyStore:
self.teams: TableActions[PrismaRecord] = db.litellm_customerteamtable # pyright: ignore[reportAttributeAccessIssue] # protocol accepts immutable query mappings
self.members: TableActions[PrismaRecord] = db.litellm_customermembertable # pyright: ignore[reportAttributeAccessIssue] # protocol accepts immutable query mappings
self.budgets: TableActions[PrismaRecord] = db.litellm_budgettable # pyright: ignore[reportAttributeAccessIssue] # protocol accepts immutable query mappings
self.window_spend: TableActions[LiteLLM_BudgetWindowSpend] = db.litellm_budgetwindowspend # pyright: ignore[reportAttributeAccessIssue] # protocol accepts immutable query mappings
async def lock_free_capacity(self) -> None:
await self.db.query_raw("SELECT 1 AS locked FROM pg_advisory_xact_lock($1)", FREE_CAPACITY_ADVISORY_LOCK)
@ -525,9 +528,10 @@ class CustomerHierarchyStore:
budgets: Final = {budget.budget_id: budget for budget in resolved}
counts: Final = await self.organization_member_counts(tuple(record.customer_org_id for record in records))
return tuple(
responses: Final = tuple(
organization_response(record, budgets, counts.get(record.customer_org_id, 0)) for record in records
)
return await customer_budget_usage(responses, self.window_spend, self.now, self.settings)
async def organization_member_counts(self, organization_ids: tuple[str, ...]) -> Mapping[str, int]:
if not organization_ids:
@ -554,11 +558,21 @@ class CustomerHierarchyStore:
async def get_team(self, team_id: str) -> Team | Failure:
row: Final = await self.teams.find_unique(where={"customer_team_id": team_id}, include=_MEMBER_INCLUDE)
return team_response(row, self.now) if row is not None else Failure(ErrorCode.NOT_FOUND)
if row is None:
return Failure(ErrorCode.NOT_FOUND)
responses: Final = await customer_budget_usage(
(team_response(row, self.now),), self.window_spend, self.now, self.settings
)
return responses[0]
async def get_member(self, member_id: str) -> CustomerMember | Failure:
row: Final = await self.members.find_unique(where={"customer_member_id": member_id}, include=_MEMBER_INCLUDE)
return member_response(row, self.now) if row is not None else Failure(ErrorCode.NOT_FOUND)
if row is None:
return Failure(ErrorCode.NOT_FOUND)
responses: Final = await customer_budget_usage(
(member_response(row, self.now),), self.window_spend, self.now, self.settings
)
return responses[0]
async def create_budget(self, budget: Budget, actor: str, name: str | None = None) -> str:
budget_id: Final = str(uuid4())
@ -959,7 +973,12 @@ class CustomerHierarchyStore:
order=[{"created_at": "asc"}, {"customer_team_id": "asc"}],
include=_MEMBER_INCLUDE,
)
return Page(tuple(team_response(row, self.now) for row in rows), count)
return Page(
await customer_budget_usage(
tuple(team_response(row, self.now) for row in rows), self.window_spend, self.now, self.settings
),
count,
)
async def list_members(
self, parent_team_id: str | None, page: int, page_size: int, *, parent_org_id: str | None = None
@ -976,7 +995,12 @@ class CustomerHierarchyStore:
order=[{"created_at": "asc"}, {"customer_member_id": "asc"}],
include=_MEMBER_INCLUDE,
)
return Page(tuple(member_response(row, self.now) for row in rows), count)
return Page(
await customer_budget_usage(
tuple(member_response(row, self.now) for row in rows), self.window_spend, self.now, self.settings
),
count,
)
async def _delete_unused_budgets(self, budget_ids: Sequence[str]) -> None:
where: Final[Mapping[str, object]] = {field: {"none": {}} for field in _BUDGET_REFERENCE_FIELDS}

View file

@ -119,12 +119,28 @@ class MemberUpsert(MemberPatch):
return self
class CustomerBudgetUsage(BaseModel):
model_config = ConfigDict(frozen=True)
source: Literal["scalar", "window"]
budget_duration: str | None
max_budget: float
spend: float | None
window_start: datetime | None = None
reset_at: datetime | None = None
class AuditFields(BaseModel):
model_config = ConfigDict(frozen=True)
alias: str | None = None
spend: float = 0.0
budget_reset_at: datetime | None = None
budget_usage: tuple[CustomerBudgetUsage, ...] | None = Field(
default=None,
description="Recorded spend for each independent effective budget. Excludes pending reservations and updates "
"after accounting flushes. Window boundaries follow the configured reset timezone and time.",
)
created_at: datetime
created_by: str
updated_at: datetime

View file

@ -0,0 +1,94 @@
import { useTranslation } from "react-i18next";
import { formatUsd } from "@/app/(dashboard)/usage/_components/components/overview/overviewData";
import { cn } from "@/lib/cva.config";
import { CUSTOMER_BUDGET_LABELS, customerBudgetPeriod, type CustomerBudgetUsage } from "./customerBudgetUsage";
function budgetPercentage(spend: number, limit: number | null): number {
if (limit === null) return 0;
if (limit === 0) return 100;
return Math.max(0, Math.min(100, (spend / limit) * 100));
}
export function CustomerBudgetWindow({
budget,
showReset = false,
}: {
budget: CustomerBudgetUsage;
showReset?: boolean;
}) {
const { t, i18n } = useTranslation();
const period = customerBudgetPeriod(budget.budget_duration);
const label = t(CUSTOMER_BUDGET_LABELS[period]);
const reset = budget.reset_at
? t("customerPortal.analytics.budgetResets", {
date: new Date(budget.reset_at).toLocaleString(i18n.resolvedLanguage, { timeZone: "UTC" }),
})
: null;
return (
<div title={[budget.budget_duration, reset].filter(Boolean).join(" · ")}>
<CustomerBudgetSpend spend={budget.spend} limit={budget.max_budget} label={label} compact={period === "yearly"} />
{showReset && reset && <p className="mt-1 text-[11px] text-muted-foreground">{reset}</p>}
</div>
);
}
export default function CustomerBudgetSpend({
spend,
limit,
label,
noLimitLabel,
compact = false,
}: {
spend: number | null;
limit: number | null;
label: string;
noLimitLabel?: string;
compact?: boolean;
}) {
const { t } = useTranslation();
const value = `${spend === null ? t("customerPortal.analytics.unknownSpend") : formatUsd(spend)} / ${limit === null ? noLimitLabel ?? t("customerPortal.analytics.noLimit") : formatUsd(limit)}`;
const atLimit = limit !== null && spend !== null && spend >= limit;
const percentage = budgetPercentage(spend ?? 0, limit);
const balance =
limit === null || spend === null
? null
: t(spend > limit ? "customerPortal.analytics.budgetOver" : "customerPortal.analytics.budgetRemaining", {
amount: formatUsd(Math.abs(limit - spend)),
});
if (compact) return <span className="whitespace-nowrap tabular-nums">{value}</span>;
return (
<div className="space-y-2 tabular-nums">
<div className="flex flex-wrap items-center justify-between gap-x-4 gap-y-1">
<span className="whitespace-nowrap font-medium">{value}</span>
{balance !== null && (
<span
className={cn(
"whitespace-nowrap rounded px-1.5 py-0.5 text-xs",
atLimit
? "bg-destructive/10 text-destructive"
: "bg-emerald-500/10 text-emerald-700 dark:text-emerald-400",
)}
>
{balance}
</span>
)}
</div>
{limit !== null && spend !== null && (
<div
role="progressbar"
aria-label={label}
aria-valuemin={0}
aria-valuemax={100}
aria-valuenow={percentage}
aria-valuetext={`${value}, ${balance}`}
className="h-1 overflow-hidden rounded-full bg-muted"
>
<div
className={cn("h-full rounded-full", atLimit ? "bg-destructive" : "bg-emerald-500")}
style={{ width: `${percentage}%` }}
/>
</div>
)}
</div>
);
}

View file

@ -1,13 +1,7 @@
import { useTranslation } from "react-i18next";
import { formatUsd } from "@/app/(dashboard)/usage/_components/components/overview/overviewData";
import { cn } from "@/lib/cva.config";
import type { CustomerUsageEntity } from "./customerUsageApi";
function budgetPercentage(spend: number, limit: number | null): number {
if (limit === null) return 0;
if (limit === 0) return 100;
return Math.max(0, Math.min(100, (spend / limit) * 100));
}
import CustomerBudgetSpend, { CustomerBudgetWindow } from "./CustomerBudgetSpend";
import { CUSTOMER_BUDGET_LABELS, customerBudgetPeriod, customerBudgetUsage } from "./customerBudgetUsage";
export default function CustomerBudgetSummary({
entity,
@ -16,41 +10,35 @@ export default function CustomerBudgetSummary({
entity: CustomerUsageEntity;
settingsHref: string;
}) {
const { t, i18n } = useTranslation();
const limit = entity.budgetLimit;
const atLimit = limit !== null && entity.spend >= limit;
const percentage = budgetPercentage(entity.spend, limit);
const cap = limit === null ? t("customerPortal.analytics.noCap") : formatUsd(limit);
const value = `${formatUsd(entity.spend)} / ${cap}`;
const { t } = useTranslation();
const budgets = customerBudgetUsage(entity);
return (
<section className="mt-3 min-w-0 space-y-1.5" aria-label={t("customerPortal.analytics.budgetSummary")}>
<section className="mt-2 min-w-0 space-y-2 text-sm" aria-label={t("customerPortal.analytics.budgetSummary")}>
<div className="flex flex-wrap items-center justify-between gap-x-3 gap-y-1 text-xs">
<span className="text-muted-foreground">{t("customerPortal.analytics.budgetSummary")}</span>
<a href={settingsHref} className="font-medium text-primary hover:underline">
{t(limit === null ? "customerPortal.analytics.setBudget" : "customerPortal.analytics.editBudget")}
{t(budgets.length > 0 ? "customerPortal.analytics.editBudget" : "customerPortal.analytics.setBudget")}
</a>
</div>
<p className={cn("text-sm font-medium tabular-nums", atLimit && "text-destructive")}>{value}</p>
{limit !== null && (
<div
role="progressbar"
aria-label={t("customerPortal.analytics.budgetSummary")}
aria-valuemin={0}
aria-valuemax={100}
aria-valuenow={percentage}
aria-valuetext={value}
className="h-1 overflow-hidden rounded-full bg-muted"
>
<div className={cn("h-full bg-primary", atLimit && "bg-destructive")} style={{ width: `${percentage}%` }} />
</div>
{budgets.map((budget) => {
const period = customerBudgetPeriod(budget.budget_duration);
return (
<div key={`${budget.source}-${budget.budget_duration}`} className="space-y-1">
<p className="text-[11px] text-muted-foreground">
{t(CUSTOMER_BUDGET_LABELS[period])}
{period === "other" && budget.budget_duration && ` (${budget.budget_duration})`}
</p>
<CustomerBudgetWindow
budget={budget}
showReset={budgets.filter((item) => customerBudgetPeriod(item.budget_duration) === period).length > 1}
/>
</div>
);
})}
{budgets.length === 0 && (
<CustomerBudgetSpend spend={entity.spend} limit={null} label={t("customerPortal.analytics.budgetSummary")} />
)}
<p className="text-[11px] text-muted-foreground">
{t("customerPortal.analytics.budgetPeriod")}
{entity.budgetResetAt &&
` · ${t("customerPortal.analytics.budgetResets", {
date: new Date(entity.budgetResetAt).toLocaleDateString(i18n.resolvedLanguage, { timeZone: "UTC" }),
})}`}
</p>
<p className="text-[11px] text-muted-foreground">{t("customerPortal.analytics.budgetUsageHint")}</p>
</section>
);
}

View file

@ -41,13 +41,16 @@ function HierarchyHeader({ hierarchy, selected }: Pick<ScopeProps, "hierarchy" |
const entity = selected.entity;
const team = selected.team;
const label = customerEntityLabel(entity);
const budget = entity.kind === "member" ? entity.record.effective_budget : entity.record.budget;
const budget = entity.kind === "organization" ? entity.record.budget : entity.record.effective_budget;
const budgetEntity: CustomerUsageEntity = {
id: customerEntityId(entity),
label,
spend: entity.record.spend,
budgetLimit: budget?.max_budget ?? null,
budgetDuration: budget?.budget_duration ?? null,
budgetLimits: budget?.budget_limits ?? [],
budgetResetAt: entity.record.budget_reset_at ?? null,
budgetUsage: entity.record.budget_usage,
};
const budgetScope = {
org: selected.organization.customer_org_id,

View file

@ -9,17 +9,12 @@ import { formatCompact, formatUsd } from "@/app/(dashboard)/usage/_components/co
import { Input } from "@/components/ui/input";
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";
import { cn } from "@/lib/cva.config";
import type { CustomerHierarchyUsage, CustomerUsageEntity } from "./customerUsageApi";
import type { CustomerHierarchyUsage } from "./customerUsageApi";
import CustomerBudgetSpend, { CustomerBudgetWindow } from "./CustomerBudgetSpend";
import { customerBudgetPeriod, customerBudgetStatus, customerBudgetUsage } from "./customerBudgetUsage";
const MEMBER_TABLE_PARSERS = { memberSearch: parseAsString.withDefault(""), memberPage: parseAsInteger.withDefault(1) };
const PAGE_SIZE = 20;
const memberStatus = (member: CustomerUsageEntity) => {
if (member.budgetLimit === null) return "customerPortal.analytics.noCap" as const;
if (member.spend > member.budgetLimit) return "customerPortal.analytics.overBudget" as const;
if (member.spend === member.budgetLimit) return "customerPortal.analytics.atBudget" as const;
return "customerPortal.analytics.withinBudget" as const;
};
export default function CustomerMemberSpend({
data,
onMemberClick,
@ -30,13 +25,17 @@ export default function CustomerMemberSpend({
const { t } = useTranslation();
const [table, setTable] = useQueryStates(MEMBER_TABLE_PARSERS);
const search = table.memberSearch;
const usage = useMemo(() => new Map(data.members.map((member) => [member.id, member])), [data.members]);
const usage = useMemo(() => new Map(data.monthlyMembers.map((member) => [member.id, member])), [data.monthlyMembers]);
const yearlyUsage = useMemo(
() => new Map(data.yearlyMembers.map((member) => [member.id, member.spend])),
[data.yearlyMembers],
);
const members = useMemo(
() =>
data.memberBudgets
.filter((member) => member.label.toLocaleLowerCase().includes(search.toLocaleLowerCase()))
.map((member) => ({ ...member, rangeUsage: usage.get(member.id) }))
.sort((a, b) => (b.rangeUsage?.spend ?? 0) - (a.rangeUsage?.spend ?? 0) || a.label.localeCompare(b.label)),
.map((member) => ({ ...member, monthlyUsage: usage.get(member.id) }))
.sort((a, b) => (b.monthlyUsage?.spend ?? 0) - (a.monthlyUsage?.spend ?? 0) || a.label.localeCompare(b.label)),
[data.memberBudgets, search, usage],
);
@ -65,15 +64,33 @@ export default function CustomerMemberSpend({
<TableHeader>
<TableRow>
<TableHead className="pl-0">{t("customerPortal.analytics.member")}</TableHead>
<TableHead className="text-right">{t("customerPortal.analytics.spend")}</TableHead>
<TableHead className="min-w-72">{t("customerPortal.analytics.monthlySpend")}</TableHead>
<TableHead className="text-right">{t("customerPortal.analytics.yearlySpend")}</TableHead>
<TableHead className="text-right">{t("customerPortal.analytics.customerSpendShare")}</TableHead>
<TableHead className="text-right">{t("customerPortal.analytics.tokens")}</TableHead>
<TableHead className="text-right">{t("customerPortal.analytics.currentBudget")}</TableHead>
<TableHead className="pr-0 text-right">{t("customerPortal.analytics.status")}</TableHead>
</TableRow>
</TableHeader>
<TableBody>
{members.slice(start, start + PAGE_SIZE).map((member) => {
const atLimit = member.budgetLimit !== null && member.spend >= member.budgetLimit;
const monthlySpend = member.monthlyUsage?.spend ?? 0;
const budgets = customerBudgetUsage(member);
const monthlyBudgets = budgets.filter(
(budget) => customerBudgetPeriod(budget.budget_duration) === "monthly",
);
const yearlyBudgets = budgets.filter((budget) => customerBudgetPeriod(budget.budget_duration) === "yearly");
const otherBudgets = budgets.filter((budget) => customerBudgetPeriod(budget.budget_duration) === "other");
const yearlySpend = yearlyUsage.get(member.id) ?? 0;
const spendShare =
data.monthlyOrganizationSpend > 0 ? (monthlySpend / data.monthlyOrganizationSpend) * 100 : 0;
const sharePercentage = Math.max(0, Math.min(100, spendShare));
const shareLabel = t("format.number", {
val: spendShare / 100,
style: "percent",
maximumFractionDigits: 1,
});
const status = customerBudgetStatus(budgets);
const atLimit = status === "customerPortal.analytics.reachedLimit";
return (
<TableRow key={member.id}>
<TableCell className="py-4 pl-0">
@ -101,14 +118,58 @@ export default function CustomerMemberSpend({
</div>
</div>
</TableCell>
<TableCell className="text-right tabular-nums">{formatUsd(member.rangeUsage?.spend ?? 0)}</TableCell>
<TableCell className="text-right tabular-nums">
{formatCompact(member.rangeUsage?.tokens ?? 0)}
<TableCell className="pr-6">
<div className="space-y-3">
{monthlyBudgets.map((budget) => (
<CustomerBudgetWindow key={budget.source} budget={budget} showReset={monthlyBudgets.length > 1} />
))}
{monthlyBudgets.length === 0 && (
<CustomerBudgetSpend
spend={monthlySpend}
limit={null}
label={t("customerPortal.analytics.monthlySpend")}
noLimitLabel={t("customerPortal.analytics.noMonthlyLimit")}
/>
)}
{otherBudgets.map((budget) => (
<div key={budget.source} className="space-y-1 text-xs text-muted-foreground">
<span>
{t("customerPortal.analytics.budgetPeriod")}
{budget.budget_duration && ` (${budget.budget_duration})`}
</span>
<CustomerBudgetWindow budget={budget} />
</div>
))}
</div>
</TableCell>
<TableCell className="text-right text-xs tabular-nums">
{member.budgetLimit === null
? t("customerPortal.analytics.noBudget")
: `${formatUsd(member.spend)} / ${formatUsd(member.budgetLimit)}`}
<TableCell className="text-right tabular-nums">
<div className="space-y-2">
{yearlyBudgets.map((budget) => (
<CustomerBudgetWindow key={budget.source} budget={budget} showReset={yearlyBudgets.length > 1} />
))}
{yearlyBudgets.length === 0 &&
`${formatUsd(yearlySpend)} / ${t("customerPortal.analytics.noYearlyLimit")}`}
</div>
</TableCell>
<TableCell>
<div
role="meter"
aria-label={t("customerPortal.analytics.customerSpendShare")}
aria-valuemin={0}
aria-valuemax={100}
aria-valuenow={sharePercentage}
aria-valuetext={shareLabel}
title={shareLabel}
className="ml-auto h-2.5 w-24 overflow-hidden rounded-full bg-muted"
>
<div
className="h-full rounded-full bg-primary"
style={{ width: `${sharePercentage}%`, opacity: 0.3 + sharePercentage * 0.007 }}
/>
</div>
</TableCell>
<TableCell className="text-right tabular-nums">
{formatCompact(member.monthlyUsage?.tokens ?? 0)}
</TableCell>
<TableCell className="pr-0 text-right">
<span
@ -117,7 +178,7 @@ export default function CustomerMemberSpend({
atLimit && "bg-destructive/10 text-destructive",
)}
>
{t(memberStatus(member))}
{t(status)}
</span>
</TableCell>
</TableRow>
@ -125,7 +186,7 @@ export default function CustomerMemberSpend({
})}
{members.length === 0 && (
<TableRow>
<TableCell colSpan={5} className="py-10 text-center text-muted-foreground">
<TableCell colSpan={6} className="py-10 text-center text-muted-foreground">
{t(search ? "customerPortal.analytics.noMatches" : "customerPortal.analytics.noMembers")}
</TableCell>
</TableRow>

View file

@ -0,0 +1,60 @@
import { describe, expect, it } from "vitest";
import { customerBudgetPeriod, customerBudgetStatus, customerBudgetUsage } from "./customerBudgetUsage";
import type { CustomerUsageEntity } from "./customerUsageApi";
const entity: CustomerUsageEntity = {
id: "member",
label: "Member",
spend: 40,
budgetLimit: 50,
budgetDuration: "1mo",
budgetResetAt: null,
budgetLimits: [
{ budget_duration: "1mo", max_budget: 10 },
{ budget_duration: "12mo", max_budget: 100 },
],
};
describe("customer budget usage", () => {
it("keeps independent counters and their limits paired, even with the same duration", () => {
const budgetUsage = [
{ source: "scalar" as const, budget_duration: "1mo", max_budget: 50, spend: 40 },
{ source: "window" as const, budget_duration: "1mo", max_budget: 10, spend: 8 },
{ source: "window" as const, budget_duration: "12mo", max_budget: 100, spend: 62 },
];
expect(customerBudgetUsage({ ...entity, budgetUsage })).toEqual(budgetUsage);
expect(customerBudgetStatus(budgetUsage)).toBe("customerPortal.analytics.withinBudget");
});
it.each([0, 10, 100])("marks a recorded exhausted limit including zero (%s)", (limit) => {
expect(customerBudgetStatus([{ source: "window", budget_duration: "12mo", max_budget: limit, spend: limit }])).toBe(
"customerPortal.analytics.reachedLimit",
);
});
it("distinguishes unavailable window usage from no budget and zero spend", () => {
const usage = customerBudgetUsage(entity);
expect(usage.map((budget) => [budget.max_budget, budget.spend])).toEqual([
[50, 40],
[10, null],
[100, null],
]);
expect(customerBudgetStatus(usage)).toBe("customerPortal.analytics.budgetUsageUnavailable");
expect(customerBudgetStatus([])).toBe("customerPortal.analytics.noLimit");
expect(customerBudgetStatus([{ source: "window", budget_duration: "1mo", max_budget: 10, spend: 0 }])).toBe(
"customerPortal.analytics.withinBudget",
);
});
it.each([
["1mo", "monthly"],
["monthly", "monthly"],
["30days", "monthly"],
["12mo", "yearly"],
["12months", "yearly"],
["365d", "other"],
[null, "other"],
] as const)("labels the configured duration %s without computing its reset", (duration, period) => {
expect(customerBudgetPeriod(duration)).toBe(period);
});
});

View file

@ -0,0 +1,48 @@
import type { components } from "@/lib/http/schema";
import type { CustomerUsageEntity } from "./customerUsageApi";
export type CustomerBudgetUsage = components["schemas"]["CustomerBudgetUsage"];
export type CustomerBudgetPeriod = "monthly" | "yearly" | "other";
export const CUSTOMER_BUDGET_LABELS = {
monthly: "customerPortal.analytics.monthlySpend",
yearly: "customerPortal.analytics.yearlySpend",
other: "customerPortal.analytics.budgetPeriod",
} as const;
export const customerBudgetPeriod = (duration: string | null): CustomerBudgetPeriod => {
const normalized = duration?.trim().toLowerCase() ?? "";
if (["1mo", "1month", "1months", "30d", "30days", "monthly"].includes(normalized)) return "monthly";
if (["12mo", "12month", "12months"].includes(normalized)) return "yearly";
return "other";
};
export const customerBudgetUsage = (entity: CustomerUsageEntity): CustomerBudgetUsage[] =>
entity.budgetUsage ?? [
...(entity.budgetLimit === null
? []
: [
{
source: "scalar" as const,
budget_duration: entity.budgetDuration,
max_budget: entity.budgetLimit,
spend: entity.spend,
reset_at: entity.budgetResetAt,
},
]),
...entity.budgetLimits.map((limit) => ({
source: "window" as const,
budget_duration: limit.budget_duration,
max_budget: limit.max_budget,
spend: null,
reset_at: limit.reset_at,
})),
];
export const customerBudgetStatus = (usage: CustomerBudgetUsage[]) => {
if (usage.some((budget) => budget.spend !== null && budget.spend >= budget.max_budget))
return "customerPortal.analytics.reachedLimit" as const;
if (usage.some((budget) => budget.spend === null)) return "customerPortal.analytics.budgetUsageUnavailable" as const;
if (usage.length === 0) return "customerPortal.analytics.noLimit" as const;
return "customerPortal.analytics.withinBudget" as const;
};

View file

@ -99,6 +99,10 @@ const request = {
accessToken: "test-session",
startDate: "2026-11-01",
endDate: "2026-11-03",
monthStartDate: "2026-11-01",
monthEndDate: "2026-11-03",
yearStartDate: "2026-01-01",
yearEndDate: "2026-11-03",
};
const list = <T>(data: T[], page = 1, totalPages = 1) => ({
data,
@ -167,6 +171,37 @@ beforeEach(() => {
afterEach(() => vi.unstubAllGlobals());
describe("customerHierarchyUsageCall", () => {
it("should preserve scalar and concurrent effective caps without treating recorded spend as window spend", async () => {
const budget = {
max_budget: 25,
budget_duration: "1mo",
budget_limits: [
{ budget_duration: "1mo", max_budget: 0, reset_at: "2026-12-01T00:00:00Z" },
{ budget_duration: "12mo", max_budget: 100, reset_at: "2027-01-01T00:00:00Z" },
],
};
fetchMock.mockImplementation((input) =>
Promise.resolve(
requestUrl(input).pathname.endsWith("/customer_members/member-a")
? json({ ...members[0], effective_budget: budget })
: serve(input),
),
);
const result = await customerHierarchyUsageCall({
...request,
scope: { org: "org-1", team: null, member: "member-a" },
});
const expected = {
spend: 40,
budgetLimit: 25,
budgetDuration: "1mo",
budgetLimits: budget.budget_limits,
};
expect(result.member).toMatchObject(expected);
expect(result.memberBudgets[0]).toEqual(result.member);
expect(result.organization.budgetLimits).toEqual([]);
});
it("should read exact daily activity routes, all pages, and scoped descendant lists", async () => {
fetchMock.mockImplementation((input) => {
const url = requestUrl(input);
@ -202,9 +237,14 @@ describe("customerHierarchyUsageCall", () => {
expect(result.memberResults).toHaveLength(1);
expect(result.memberResults[0].breakdown.entities["member-b"].metrics.total_tokens).toBe(500);
expect(result.memberBudgets[0]).toMatchObject({ id: "member-a", spend: 40, budgetLimit: 10 });
expect(result.yearlyMembers.map((member) => member.spend)).toEqual([3, 1]);
for (const url of dailyUrls()) {
expect(url.pathname).toMatch(/^\/management\/v1\/customer_(organizations|teams|members)\/daily\/activity$/);
expect(url.searchParams.get("start_date")).toBe(request.startDate);
expect(url.searchParams.get("start_date")).toBe(
url.pathname.includes("customer_members") && url.searchParams.get("start_date") === request.yearStartDate
? request.yearStartDate
: request.startDate,
);
expect(url.searchParams.get("end_date")).toBe(request.endDate);
expect(url.searchParams.get("page_size")).toBe("100");
expect([...url.searchParams.keys()].filter((name) => name.endsWith("_ids"))).toHaveLength(1);
@ -252,11 +292,35 @@ describe("customerHierarchyUsageCall", () => {
expect(Object.keys(result.teamResults[0].breakdown.entities)).toEqual(["team-a"]);
expect(result.teamResults[0].breakdown.entities["team-a"].metrics.spend).toBe(3);
expect(result.memberResults[0].breakdown.entities["member-a"].metrics.total_tokens).toBe(100);
expect(dailyUrls()).toHaveLength(1);
expect(dailyUrls()[0].searchParams.get("customer_member_ids")).toBe("member-a");
const memberReads = dailyUrls().filter((url) => url.searchParams.has("customer_member_ids"));
expect(memberReads.map((url) => url.searchParams.get("start_date"))).toEqual([
request.startDate,
request.yearStartDate,
]);
expect(memberReads[0].searchParams.get("customer_member_ids")).toBe("member-a");
expect(result.monthlyOrganizationSpend).toBe(4);
expect(result.monthlyMembers.find((member) => member.id === "member-a")?.spend).toBe(3);
expect(result.yearlyMembers.find((member) => member.id === "member-a")?.spend).toBe(3);
expect(urls().some((url) => url.pathname === "/management/v1/customer_members")).toBe(false);
});
it("should retain both periods when the selected chart range is the current year", async () => {
const yearRequest = {
...request,
scope: { org: "org-1", team: null, member: "member-a" },
startDate: request.yearStartDate,
endDate: request.yearEndDate,
};
const result = await customerHierarchyUsageCall(yearRequest);
expect(result.yearlyMembers).toEqual(result.members);
expect(result.monthlyMembers.find((member) => member.id === "member-a")?.spend).toBe(3);
expect(
dailyUrls()
.filter((url) => url.searchParams.has("customer_member_ids"))
.map((url) => url.searchParams.get("start_date")),
).toEqual([request.yearStartDate, request.monthStartDate]);
});
it("should reject mismatched ancestry before requesting any usage", async () => {
fetchMock.mockImplementation((input) =>
Promise.resolve(
@ -271,6 +335,29 @@ describe("customerHierarchyUsageCall", () => {
expect(dailyUrls()).toHaveLength(0);
});
it("should read monthly member totals and the whole organization independently of a team's selected chart dates", async () => {
fetchMock.mockImplementation((input) => {
const url = requestUrl(input);
if (url.pathname.endsWith("/daily/activity") && url.searchParams.get("start_date") === "2026-10-01")
return Promise.resolve(json({ results: [], metadata: EMPTY_DAILY_ACTIVITY_METADATA }));
return Promise.resolve(serve(input));
});
const teamRequest = {
...request,
scope: { org: "org-1", team: "team-a", member: null },
startDate: "2026-10-01",
endDate: "2026-10-31",
};
const result = await customerHierarchyUsageCall(teamRequest);
expect(result.metadata.total_spend).toBe(0);
expect(result.monthlyOrganizationSpend).toBe(4);
expect(result.monthlyMembers.find((member) => member.id === "member-a")?.spend).toBe(3);
expect(result.yearlyMembers.find((member) => member.id === "member-a")?.spend).toBe(3);
const organizationReads = dailyUrls().filter((url) => url.searchParams.has("customer_org_ids"));
expect(organizationReads.map((url) => url.searchParams.get("page"))).toEqual(["1", "2"]);
expect(organizationReads.every((url) => url.searchParams.get("start_date") === request.monthStartDate)).toBe(true);
});
it("should never send an empty descendant filter and should retain unassigned usage", async () => {
fetchMock.mockImplementation((input) =>
Promise.resolve(requestUrl(input).pathname === "/management/v1/customer_teams" ? json(list([])) : serve(input)),

View file

@ -27,7 +27,10 @@ export interface CustomerUsageEntity {
label: string;
spend: number;
budgetLimit: number | null;
budgetDuration: string | null;
budgetLimits: components["schemas"]["BudgetLimit"][];
budgetResetAt: string | null;
budgetUsage?: components["schemas"]["CustomerBudgetUsage"][] | null;
}
export interface CustomerHierarchyUsage extends ReturnType<typeof mergeCustomerActivityPages> {
@ -40,6 +43,9 @@ export interface CustomerHierarchyUsage extends ReturnType<typeof mergeCustomerA
teamResults: ReturnType<typeof mergeCustomerActivityPages>["results"];
memberResults: ReturnType<typeof mergeCustomerActivityPages>["results"];
memberBudgets: CustomerUsageEntity[];
monthlyOrganizationSpend: number;
monthlyMembers: UsageRow[];
yearlyMembers: UsageRow[];
}
interface CustomerUsageRequest {
@ -47,6 +53,10 @@ interface CustomerUsageRequest {
accessToken: string;
startDate: string;
endDate: string;
monthStartDate: string;
monthEndDate: string;
yearStartDate: string;
yearEndDate: string;
signal?: AbortSignal;
}
@ -136,7 +146,7 @@ const activityPages = async (resource: Collection, ids: readonly string[], reque
};
interface ActivityJob {
dimension: "scope" | "teams" | "members";
dimension: "scope" | "teams" | "members" | "monthlyOrganization" | "monthlyMembers" | "yearlyMembers";
resource: Collection;
ids: readonly string[];
}
@ -148,13 +158,19 @@ const chunkJobs = (resource: Collection, dimension: ActivityJob["dimension"], id
ids: ids.slice(index * PAGE_SIZE, (index + 1) * PAGE_SIZE),
}));
const entity = (id: string, record: Organization | Team | Member): CustomerUsageEntity => ({
id,
label: record.alias || id,
spend: record.spend,
budgetLimit: ("effective_budget" in record ? record.effective_budget : record.budget)?.max_budget ?? null,
budgetResetAt: record.budget_reset_at ?? null,
});
const entity = (id: string, record: Organization | Team | Member): CustomerUsageEntity => {
const budget = "effective_budget" in record ? record.effective_budget : record.budget;
return {
id,
label: record.alias || id,
spend: record.spend,
budgetLimit: budget?.max_budget ?? null,
budgetDuration: budget?.budget_duration ?? null,
budgetLimits: budget?.budget_limits ?? [],
budgetResetAt: record.budget_reset_at ?? null,
budgetUsage: record.budget_usage,
};
};
const selectedResource = (scope: ResolvedScope): Collection => {
if (scope.member) return "customer_members";
@ -162,6 +178,21 @@ const selectedResource = (scope: ResolvedScope): Collection => {
return "customer_organizations";
};
const monthlyJobs = (
isCurrentMonth: boolean,
resource: Collection,
organizationId: string,
memberIds: readonly string[],
): ActivityJob[] => [
...(!isCurrentMonth || resource !== "customer_organizations"
? chunkJobs("customer_organizations", "monthlyOrganization", [organizationId])
: []),
...(!isCurrentMonth ? chunkJobs("customer_members", "monthlyMembers", memberIds) : []),
];
const isSelectedRange = (request: CustomerUsageRequest, startDate: string, endDate: string): boolean =>
request.startDate === startDate && request.endDate === endDate;
export const customerHierarchyUsageCall = async (request: CustomerUsageRequest): Promise<CustomerHierarchyUsage> => {
assertIdentifiers([
request.scope.org,
@ -171,6 +202,8 @@ export const customerHierarchyUsageCall = async (request: CustomerUsageRequest):
const children = await descendants(selected, request);
const resource = selectedResource(selected);
const selectedId = selected.member?.customer_member_id ?? selected.team?.customer_team_id ?? request.scope.org;
const isCurrentMonth = isSelectedRange(request, request.monthStartDate, request.monthEndDate);
const isCurrentYear = isSelectedRange(request, request.yearStartDate, request.yearEndDate);
const jobs: ActivityJob[] = [
{ dimension: "scope", resource, ids: [selectedId] },
...(!selected.team
@ -187,10 +220,33 @@ export const customerHierarchyUsageCall = async (request: CustomerUsageRequest):
children.members.map((member) => member.customer_member_id),
)
: []),
...monthlyJobs(
isCurrentMonth,
resource,
request.scope.org,
children.members.map((member) => member.customer_member_id),
),
...(!isCurrentYear
? chunkJobs(
"customer_members",
"yearlyMembers",
children.members.map((member) => member.customer_member_id),
)
: []),
];
const monthRequest = { ...request, startDate: request.monthStartDate, endDate: request.monthEndDate };
const yearRequest = { ...request, startDate: request.yearStartDate, endDate: request.yearEndDate };
const requests: Record<ActivityJob["dimension"], CustomerUsageRequest> = {
scope: request,
teams: request,
members: request,
monthlyOrganization: monthRequest,
monthlyMembers: monthRequest,
yearlyMembers: yearRequest,
};
const activity = await batches(jobs, async (job) => ({
dimension: job.dimension,
pages: await activityPages(job.resource, job.ids, request),
pages: await activityPages(job.resource, job.ids, requests[job.dimension]),
}));
const primary = mergeCustomerActivityPages(
activity.filter((result) => result.dimension === "scope").flatMap((result) => result.pages),
@ -205,6 +261,22 @@ export const customerHierarchyUsageCall = async (request: CustomerUsageRequest):
: mergeCustomerActivityPages(
activity.filter((result) => result.dimension === "members").flatMap((result) => result.pages),
).results;
const monthlyOrganization =
isCurrentMonth && resource === "customer_organizations"
? primary
: mergeCustomerActivityPages(
activity.filter((result) => result.dimension === "monthlyOrganization").flatMap((result) => result.pages),
);
const monthlyMemberDays = isCurrentMonth
? memberDays
: mergeCustomerActivityPages(
activity.filter((result) => result.dimension === "monthlyMembers").flatMap((result) => result.pages),
).results;
const yearlyMemberActivity = isCurrentYear
? { results: memberDays, metadata: primary.metadata }
: mergeCustomerActivityPages(
activity.filter((result) => result.dimension === "yearlyMembers").flatMap((result) => result.pages),
);
const teamLabels = new Map(
children.teams.map((team) => [team.customer_team_id, team.alias || team.customer_team_id]),
);
@ -232,5 +304,12 @@ export const customerHierarchyUsageCall = async (request: CustomerUsageRequest):
),
memberResults: customerEntityDailyData(primary.results, memberDays, memberLabels),
memberBudgets: children.members.map((member) => entity(member.customer_member_id, member)),
monthlyOrganizationSpend: monthlyOrganization.metadata.total_spend,
monthlyMembers: customerEntityRankings(monthlyMemberDays, memberLabels, monthlyOrganization.metadata, {
unassignedLabel: i18n.t("customerPortal.analytics.unassignedMember"),
}),
yearlyMembers: customerEntityRankings(yearlyMemberActivity.results, memberLabels, yearlyMemberActivity.metadata, {
unassignedLabel: i18n.t("customerPortal.analytics.unassignedMember"),
}),
};
};

View file

@ -38,10 +38,21 @@ const day = (date: string, total: SpendMetrics, breakdown: Partial<DailyData["br
});
const snapshot = (): CustomerHierarchyUsage => ({
organization: { id: "org", label: "Organization", spend: 0, budgetLimit: null, budgetResetAt: null },
organization: {
id: "org",
label: "Organization",
spend: 0,
budgetLimit: null,
budgetDuration: null,
budgetLimits: [],
budgetResetAt: null,
},
team: null,
member: null,
memberBudgets: [],
monthlyOrganizationSpend: 0,
monthlyMembers: [],
yearlyMembers: [],
metadata: { ...EMPTY_DAILY_ACTIVITY_METADATA },
results: [
day("2026-11-01", metrics(100, 1_000, 100), {

View file

@ -1,7 +1,6 @@
import { describe, expect, it } from "vitest";
import type { DailyData, MetricWithMetadata, SpendMetrics } from "@/components/UsagePage/types";
import { rankCustomerModels, rankCustomerUsage, type CustomerUsageRow } from "./customerUsageData";
const metrics = (spend: number, tokens: number, requests: number): SpendMetrics => ({
spend,
prompt_tokens: tokens,

View file

@ -9,7 +9,6 @@ import {
rollUpBreakdown,
type UsageMetric,
} from "@/app/(dashboard)/usage/_components/components/overview/overviewData";
export interface CustomerUsageTotals {
spend: number;
tokens: number;

View file

@ -21,6 +21,7 @@ import type { DailyData } from "@/components/UsagePage/types";
import { customerHierarchyUsageCall, type CustomerUsageScope } from "./customerUsageApi";
import { rankCustomerModels, rankCustomerUsage } from "./customerUsageData";
import { CUSTOMER_USAGE_DIMENSIONS, type CustomerUsageDimension } from "./CustomerUsageRankings";
import { calendarDate, customerPresetRange } from "./customerUsageRange";
const usageParsers = {
org: parseAsString,
@ -60,9 +61,30 @@ export default function useCustomerHierarchyUsage() {
const endDate = dateValue.to ? formatDate(dateValue.to) : undefined;
const scope = params.org ? { org: params.org, team: params.team, member: params.member } : null;
const request = usageRequest(scope, accessToken, startDate, endDate);
const month = customerPresetRange("month");
const monthStartDate = calendarDate(month.from);
const monthEndDate = calendarDate(month.to);
const year = customerPresetRange("YTD");
const yearStartDate = calendarDate(year.from);
const yearEndDate = calendarDate(year.to);
const usage = useQuery({
queryKey: ["customer-hierarchy", "usage", params.org, params.team, params.member, startDate, endDate],
queryFn: request ? ({ signal }) => customerHierarchyUsageCall({ ...request, signal }) : skipToken,
queryKey: [
"customer-hierarchy",
"usage",
params.org,
params.team,
params.member,
startDate,
endDate,
monthStartDate,
yearEndDate,
],
queryFn: request
? ({ signal }) => {
const periodRequest = { ...request, monthStartDate, monthEndDate, yearStartDate, yearEndDate, signal };
return customerHierarchyUsageCall(periodRequest);
}
: skipToken,
});
const data = usage.data;
const results = data?.results ?? EMPTY_RESULTS;

View file

@ -134,7 +134,7 @@ describe("customer hierarchy management", () => {
const table = await screen.findByRole("table", { name: "Customer teams" });
expect(within(table).getByRole("button", { name: "Product" })).toBeInTheDocument();
expect(screen.getByRole("heading", { name: "Example customer" })).toBeInTheDocument();
expect(screen.getByRole("progressbar", { name: "Current budget" })).toHaveAttribute("aria-valuenow", "12");
expect(screen.getByRole("progressbar", { name: "Recorded budget spend" })).toHaveAttribute("aria-valuenow", "12");
expect(
requestedUrls()
.find((url) => url.pathname === "/management/v1/customer_teams")
@ -152,6 +152,33 @@ describe("customer hierarchy management", () => {
]);
});
it("should show effective member window limits without treating them as an absent budget", async () => {
fetchMock.mockImplementation(async (input) =>
requestUrl(input).pathname === "/management/v1/customer_members/member-a"
? json({
...member,
effective_budget: {
max_budget: null,
budget_limits: [
{ budget_duration: "1mo", max_budget: 10 },
{ budget_duration: "12mo", max_budget: 100 },
],
},
})
: serve(input),
);
renderWithProviders(<CustomerHierarchyManager />, { searchParams: "?org=org-1&team=team-a&member=member-a" });
const summary = await screen.findByRole("region", { name: "Current budget" });
expect(within(summary).getByText("Unavailable / $10.00")).toBeInTheDocument();
expect(within(summary).getByText("Unavailable / $100.00")).toBeInTheDocument();
expect(within(summary).getByRole("link", { name: "Edit budget" })).toHaveAttribute(
"href",
`${uiHref("customers/manage")}?org=org-1&team=team-a&member=member-a&tab=settings`,
);
expect(within(summary).queryByText(/No limit/)).not.toBeInTheDocument();
expect(within(summary).queryByRole("progressbar")).not.toBeInTheDocument();
});
it("should list customer members across an organization and open their customer team context", async () => {
const user = userEvent.setup();
const onUrlUpdate = vi.fn();

View file

@ -61,6 +61,19 @@ const members = [
},
];
const records = [
...[
{ date: "2026-03-01", spend: 42 },
{ date: "2025-12-31", spend: 100 },
].map(({ date, spend }) => ({
organization: "org-1",
team: "team-a",
member: "member-a",
model: "model-a",
key: "hash-a",
alias: "Assistant key",
metrics: metrics(spend, 50, 1),
date,
})),
{
organization: "org-1",
team: "team-a",
@ -81,6 +94,26 @@ const records = [
metrics: metrics(3, 600, 5),
date: "2026-11-02",
},
{
organization: "org-1",
team: "team-a",
member: "member-a",
model: "model-a",
key: "hash-a",
alias: "Assistant key",
metrics: metrics(8, 300, 1),
date: "2026-11-10",
},
{
organization: "org-1",
team: "",
member: "",
model: "model-a",
key: "hash-c",
alias: "Organization key",
metrics: metrics(7, 200, 1),
date: "2026-11-10",
},
];
const fetchMock = vi.fn<typeof fetch>();
const json = (body: unknown, status = 200) =>
@ -104,10 +137,13 @@ const filterFor = (resource: string | undefined) =>
team: "customer_team_ids",
member: "customer_member_ids",
})[activityDimension(resource)];
const activityUrl = (resource: string, id: string) => {
const activityUrl = (resource: string, id: string, endDate = "2026-11-03") => {
const filter = filterFor(resource);
return requestedUrls().findLast(
(url) => url.pathname === `/management/v1/${resource}/daily/activity` && url.searchParams.get(filter) === id,
(url) =>
url.pathname === `/management/v1/${resource}/daily/activity` &&
url.searchParams.get(filter) === id &&
url.searchParams.get("end_date") === endDate,
);
};
const serve = (input: Parameters<typeof fetch>[0]): Response => {
@ -117,7 +153,13 @@ const serve = (input: Parameters<typeof fetch>[0]): Response => {
const dimension = activityDimension(resource);
const filter = filterFor(resource);
const ids = url.searchParams.get(filter)?.split(",") ?? [];
const selected = records.filter((record) => ids.includes(record[dimension]));
const selected = records
.filter((record) => ids.includes(record[dimension]))
.filter(
(record) =>
record.date >= (url.searchParams.get("start_date") ?? "") &&
record.date <= (url.searchParams.get("end_date") ?? ""),
);
const results = selected.map((record) => {
const key = { metrics: record.metrics, metadata: { key_alias: record.alias, team_id: null } };
const entry = { metrics: record.metrics, metadata: {}, api_key_breakdown: { [record.key]: key } };
@ -148,6 +190,8 @@ const serve = (input: Parameters<typeof fetch>[0]): Response => {
describe("CustomerHierarchyUsagePage", () => {
beforeEach(() => {
vi.useFakeTimers({ toFake: ["Date"] });
vi.setSystemTime(new Date("2026-11-13T12:00:00Z"));
testQueryClient.clear();
registerBaseUrlGetter(() => "http://localhost");
fetchMock.mockReset();
@ -160,6 +204,7 @@ describe("CustomerHierarchyUsagePage", () => {
});
afterEach(() => {
vi.useRealTimers();
testQueryClient.clear();
vi.unstubAllGlobals();
});
@ -231,7 +276,7 @@ describe("CustomerHierarchyUsagePage", () => {
expect(activityUrl("customer_teams", "team-a")?.pathname).toBe("/management/v1/customer_teams/daily/activity");
expect(activityUrl("customer_teams", "team-a")?.searchParams.get("customer_team_ids")).toBe("team-a");
const teamBudget = screen.getByRole("region", { name: "Current budget" });
expect(within(teamBudget).getByText("$40.00 / No cap")).toBeInTheDocument();
expect(within(teamBudget).getByText("$40.00 / No limit")).toBeInTheDocument();
expect(within(teamBudget).getByRole("link", { name: "Set budget" })).toHaveAttribute(
"href",
"/ui/customers/manage?org=org-1&team=team-a&tab=settings",
@ -280,16 +325,20 @@ describe("CustomerHierarchyUsagePage", () => {
]);
});
it("should retain a separate member spend table with range usage and current budget status across chart breakdowns", async () => {
it("should retain monthly member usage and whole-customer shares across chart breakdowns", async () => {
const user = userEvent.setup();
const onUrlUpdate = vi.fn();
renderWithProviders(<CustomerHierarchyUsagePage />, { searchParams: initialUrl, onUrlUpdate });
const table = await screen.findByRole("table", { name: "Customer member spend" });
const firstMember = within(table).getAllByRole("row")[1];
expect(firstMember).toHaveTextContent("Member One");
expect(within(firstMember).getByText("$12.00")).toBeInTheDocument();
expect(within(firstMember).getByText("$40.00 / $10.00")).toBeInTheDocument();
expect(within(firstMember).getByText("Over budget")).toBeInTheDocument();
expect(within(firstMember).getByText("$20.00 / No monthly limit")).toBeInTheDocument();
expect(within(firstMember).getByRole("meter", { name: "Share of customer spend" })).toHaveAttribute(
"aria-valuetext",
"66.7%",
);
expect(firstMember).toHaveTextContent("Recorded budget spend$40.00 / $10.00");
expect(within(firstMember).getByText("Reached limit")).toBeInTheDocument();
await selectBreakdown(user, "Customer teams");
await user.click(screen.getByRole("radio", { name: "Tokens" }));
@ -335,6 +384,105 @@ describe("CustomerHierarchyUsagePage", () => {
);
});
it.each([
{ monthlySpend: 8, yearlySpend: 62, status: "Within budget" },
{ monthlySpend: 10, yearlySpend: 62, status: "Reached limit" },
{ monthlySpend: 8, yearlySpend: 100, status: "Reached limit" },
])(
"should use each recorded budget window consistently across the table and summary (%#)",
async ({ monthlySpend, yearlySpend, status }) => {
const user = userEvent.setup();
const budgetUsage = [
{ source: "scalar", budget_duration: "1mo", max_budget: 50, spend: 40, reset_at: "2026-12-01T00:00:00Z" },
{
source: "window",
budget_duration: "1mo",
max_budget: 10,
spend: monthlySpend,
window_start: "2026-11-01T17:00:00Z",
reset_at: "2026-12-01T17:00:00Z",
},
{
source: "window",
budget_duration: "12mo",
max_budget: 100,
spend: yearlySpend,
window_start: "2026-01-01T17:00:00Z",
reset_at: "2027-01-01T17:00:00Z",
},
];
fetchMock.mockImplementation((input) => {
const url = requestUrl(input);
const member = {
...members[0],
budget_usage: budgetUsage,
effective_budget: {
max_budget: 50,
budget_duration: "1mo",
budget_limits: [
{ budget_duration: "1mo", max_budget: 10 },
{ budget_duration: "12mo", max_budget: 100 },
],
},
};
if (url.pathname === "/management/v1/customer_members")
return Promise.resolve(json(list(url.searchParams.get("parent_team_id") === "team-a" ? [member] : [])));
if (url.pathname.endsWith("/customer_members/member-a")) return Promise.resolve(json(member));
return Promise.resolve(serve(input));
});
renderWithProviders(<CustomerHierarchyUsagePage />, { searchParams: initialUrl });
const table = await screen.findByRole("table", { name: "Customer member spend" });
const row = within(table).getAllByRole("row")[1];
expect(within(row).getByText("$40.00 / $50.00")).toBeInTheDocument();
expect(within(row).getByText(`$${monthlySpend.toFixed(2)} / $10.00`)).toBeInTheDocument();
expect(within(row).getByText(`$${yearlySpend.toFixed(2)} / $100.00`)).toBeInTheDocument();
expect(
within(row)
.getAllByRole("progressbar")
.map((bar) => bar.getAttribute("aria-valuenow")),
).toEqual(["80", String(monthlySpend * 10)]);
expect(within(row).getByRole("meter", { name: "Share of customer spend" })).toHaveAttribute(
"aria-valuetext",
"66.7%",
);
expect(within(row).getAllByRole("cell")[5]).toHaveTextContent(status);
await user.click(within(row).getByRole("button", { name: "Member One" }));
expect(await screen.findByRole("heading", { name: "Member One" })).toBeInTheDocument();
const summary = screen.getByRole("region", { name: "Current budget" });
expect(within(summary).getByText("$40.00 / $50.00")).toBeInTheDocument();
expect(within(summary).getByText(`$${monthlySpend.toFixed(2)} / $10.00`)).toBeInTheDocument();
expect(within(summary).getByText(`$${yearlySpend.toFixed(2)} / $100.00`)).toBeInTheDocument();
expect(
within(summary)
.getAllByRole("progressbar")
.map((bar) => bar.getAttribute("aria-valuenow")),
).toEqual(["80", String(monthlySpend * 10)]);
},
);
it("should retain limits but not invent window spend when an older backend omits usage", async () => {
fetchMock.mockImplementation((input) => {
const url = requestUrl(input);
if (url.pathname === "/management/v1/customer_members")
return Promise.resolve(
json(
list(
url.searchParams.get("parent_team_id") === "team-a"
? [{ ...members[0], effective_budget: { budget_limits: [{ budget_duration: "1mo", max_budget: 10 }] } }]
: [],
),
),
);
return Promise.resolve(serve(input));
});
renderWithProviders(<CustomerHierarchyUsagePage />, { searchParams: initialUrl });
const table = await screen.findByRole("table", { name: "Customer member spend" });
const row = within(table).getAllByRole("row")[1];
expect(within(row).getByText("Unavailable / $10.00")).toBeInTheDocument();
expect(within(row).getByText("Budget usage unavailable")).toBeInTheDocument();
expect(within(row).queryByRole("progressbar")).not.toBeInTheDocument();
});
it("should request a changed date range without showing stale totals or losing the customer scope", async () => {
const user = userEvent.setup();
const onUrlUpdate = vi.fn();
@ -355,10 +503,14 @@ describe("CustomerHierarchyUsagePage", () => {
await user.click(screen.getByRole("button", { name: "Apply" }));
await waitFor(() =>
expect(activityUrl("customer_organizations", "org-1")?.searchParams.get("start_date")).toBe("2026-10-01"),
expect(activityUrl("customer_organizations", "org-1", "2026-10-07")?.searchParams.get("start_date")).toBe(
"2026-10-01",
),
);
expect(activityUrl("customer_organizations", "org-1")?.searchParams.get("end_date")).toBe("2026-10-07");
expect(activityUrl("customer_organizations", "org-1")?.pathname).toBe(
expect(activityUrl("customer_organizations", "org-1", "2026-10-07")?.searchParams.get("end_date")).toBe(
"2026-10-07",
);
expect(activityUrl("customer_organizations", "org-1", "2026-10-07")?.pathname).toBe(
"/management/v1/customer_organizations/daily/activity",
);
expect(screen.getByRole("status", { name: "Loading customer usage" })).toBeInTheDocument();
@ -425,7 +577,7 @@ describe("CustomerHierarchyUsagePage", () => {
const budget = await screen.findByRole("region", { name: "Current budget" });
expect(within(budget).getByText("$40.00 / $0.00")).toBeInTheDocument();
expect(within(budget).getByRole("progressbar")).toHaveAttribute("aria-valuenow", "100");
expect(within(budget).getByText(/Configured reset:.*UTC/)).toBeInTheDocument();
expect(within(budget).getByTitle(/Configured reset:.*UTC/)).toBeInTheDocument();
expect(within(budget).queryByRole("link", { name: "Set budget" })).not.toBeInTheDocument();
});
});

View file

@ -42,7 +42,9 @@ export default function UsageStatStrip({
: t("usage.statStrip.noBudget");
return (
<div className="grid grid-cols-1 overflow-hidden rounded-xl border bg-card sm:grid-cols-2 lg:grid-cols-4 lg:divide-x">
<StatCell trend={<Sparkline data={daily} dataKey="spend" color={BRAND} className="h-14" />}>
<StatCell
trend={daily.length > 1 ? <Sparkline data={daily} dataKey="spend" color={BRAND} className="h-14" /> : undefined}
>
<Stat
label={t("usage.statStrip.spend")}
value={t("format.usd", { val: totals.spend })}
@ -51,7 +53,11 @@ export default function UsageStatStrip({
/>
{spendDetails}
</StatCell>
<StatCell trend={<Sparkline data={daily} dataKey="requests" color={BRAND} className="h-14" />}>
<StatCell
trend={
daily.length > 1 ? <Sparkline data={daily} dataKey="requests" color={BRAND} className="h-14" /> : undefined
}
>
<Stat
label={t("usage.statStrip.totalRequests")}
value={t("format.number", { val: totals.requests })}
@ -84,7 +90,11 @@ export default function UsageStatStrip({
</div>
)}
</StatCell>
<StatCell trend={<Sparkline data={daily} dataKey="tokens" color={BRAND} className="h-14" />}>
<StatCell
trend={
daily.length > 1 ? <Sparkline data={daily} dataKey="tokens" color={BRAND} className="h-14" /> : undefined
}
>
<Stat
label={t("usage.statStrip.totalTokens")}
value={loading ? null : t("format.compactNumber", { val: totals.tokens })}

View file

@ -20912,7 +20912,7 @@
"previous": "Previous",
"next": "Next",
"allOrganizationUsage": "View all customer organization usage",
"freshness": "Usage appears after accounting completes. Date ranges use UTC. Budgets compare recorded spend with the configured cap.",
"freshness": "Usage appears after accounting completes. Date ranges use UTC. Budget resets follow the configured period.",
"scopeMismatch": "This customer team or customer member does not belong to the selected customer organization.",
"invalidIdentifier": "Select a valid customer identifier.",
"incompletePages": "Could not load the complete usage range. Please choose fewer days.",
@ -20932,12 +20932,28 @@
"topTeams": "Top customer teams",
"topMembers": "Top customer members",
"memberSpend": "Customer member spend",
"memberSpendHint": "Usage in the selected date range. Cap status uses each customer member’s recorded budget spend.",
"memberSpendHint": "Budget spend follows each configured reset period. Share and tokens use the current UTC calendar month. These values are independent of the chart date range.",
"searchMembers": "Search customer members",
"member": "$t(customerPortal.entities.member)",
"currentBudget": "Spend / cap",
"currentBudget": "Spend / limit",
"status": "Status",
"noCap": "No cap",
"noLimit": "No limit",
"limitConfigured": "Limit configured",
"monthlySpend": "Spend this month / monthly limit",
"yearlySpend": "Yearly spend / yearly limit",
"customerSpendShare": "Share of customer spend",
"noMonthlyLimit": "No monthly limit",
"noYearlyLimit": "No yearly limit",
"reachedLimit": "Reached limit",
"withinMonthlyBudget": "Within monthly limit",
"monthlyLimitAmount": "Monthly limit: {{amount}}",
"yearlyLimitAmount": "Yearly limit: {{amount}}",
"budgetRemaining": "{{amount}} remains",
"budgetOver": "{{amount}} over",
"calendarMonth": "Current UTC calendar month",
"budgetUsageHint": "Recorded spend updates after accounting completes. Pending requests are excluded.",
"budgetUsageUnavailable": "Budget usage unavailable",
"unknownSpend": "Unavailable",
"atBudget": "At budget",
"withinBudget": "Within budget",
"noMembers": "No customer members in this customer scope.",

View file

@ -33374,6 +33374,24 @@ export interface components {
*/
type: "custom";
};
/** CustomerBudgetUsage */
CustomerBudgetUsage: {
/** Budget Duration */
budget_duration: string | null;
/** Max Budget */
max_budget: number;
/** Reset At */
reset_at?: string | null;
/**
* Source
* @enum {string}
*/
source: "scalar" | "window";
/** Spend */
spend: number | null;
/** Window Start */
window_start?: string | null;
};
/**
* CustomerHierarchyAuth
* @description The levels a request is charged to. A request that named only an organization alias has no team or member.
@ -33413,6 +33431,11 @@ export interface components {
budget_override_id?: string | null;
/** Budget Reset At */
budget_reset_at?: string | null;
/**
* Budget Usage
* @description Recorded spend for each independent effective budget. Excludes pending reservations and updates after accounting flushes. Window boundaries follow the configured reset timezone and time.
*/
budget_usage?: components["schemas"]["CustomerBudgetUsage"][] | null;
/**
* Created At
* Format: date-time
@ -40814,6 +40837,11 @@ export interface components {
budget_override_id?: string | null;
/** Budget Reset At */
budget_reset_at?: string | null;
/**
* Budget Usage
* @description Recorded spend for each independent effective budget. Excludes pending reservations and updates after accounting flushes. Window boundaries follow the configured reset timezone and time.
*/
budget_usage?: components["schemas"]["CustomerBudgetUsage"][] | null;
/** Created */
created: boolean;
/**
@ -42714,6 +42742,11 @@ export interface components {
budget_id?: string | null;
/** Budget Reset At */
budget_reset_at?: string | null;
/**
* Budget Usage
* @description Recorded spend for each independent effective budget. Excludes pending reservations and updates after accounting flushes. Window boundaries follow the configured reset timezone and time.
*/
budget_usage?: components["schemas"]["CustomerBudgetUsage"][] | null;
/**
* Created At
* Format: date-time
@ -42909,6 +42942,11 @@ export interface components {
budget_id?: string | null;
/** Budget Reset At */
budget_reset_at?: string | null;
/**
* Budget Usage
* @description Recorded spend for each independent effective budget. Excludes pending reservations and updates after accounting flushes. Window boundaries follow the configured reset timezone and time.
*/
budget_usage?: components["schemas"]["CustomerBudgetUsage"][] | null;
/** Created */
created: boolean;
/**
@ -49724,6 +49762,11 @@ export interface components {
budget_override_id?: string | null;
/** Budget Reset At */
budget_reset_at?: string | null;
/**
* Budget Usage
* @description Recorded spend for each independent effective budget. Excludes pending reservations and updates after accounting flushes. Window boundaries follow the configured reset timezone and time.
*/
budget_usage?: components["schemas"]["CustomerBudgetUsage"][] | null;
/**
* Created At
* Format: date-time

View file

@ -1622,3 +1622,31 @@ def test_member_in_two_teams_is_listed_under_each_and_teams_from_another_organiz
assert mixed.status_code == 404, mixed.text
fetched: Final = http.get("/management/v1/customer_organizations/org")
assert fetched.json()["member_count"] == 1
def test_list_and_detail_expose_each_effective_budget_with_its_own_recorded_spend() -> None:
database: Final = Database()
http: Final = client(database=database)
family(http)
created: Final = http.post(
"/management/v1/customer_members",
json={
"customer_member_id": "window-member", "parent_team_ids": ["team"],
"budget_override": {
"max_budget": 50, "budget_duration": "1mo",
"budget_limits": [{"budget_duration": "1mo", "max_budget": 10}],
},
},
)
assert created.status_code == 201, created.text
database.litellm_budgetwindowspend.rows = {
"window-member": Record(
entity_type="customer_member", entity_id="window-member", window_duration="1mo",
window_start=NOW, spend=8,
),
}
detail: Final = http.get("/management/v1/customer_members/window-member")
listing: Final = http.get("/management/v1/customer_members?parent_team_id=team")
assert detail.status_code == listing.status_code == 200
assert listing.json()["data"][0]["budget_usage"] == detail.json()["budget_usage"]
assert [(item["spend"], item["max_budget"]) for item in detail.json()["budget_usage"]] == [(0, 50), (8, 10)]

View file

@ -0,0 +1,80 @@
from datetime import datetime, time, timezone
from typing import Final, cast
import pytest
from prisma.models import LiteLLM_BudgetWindowSpend
from litellm.models.budget import BudgetLimit
from litellm.proxy.common_utils.timezone_utils import BudgetResetSettings
from litellm.proxy.management_helpers.customer_budget_usage import customer_budget_usage
from litellm.proxy.spend_tracking.budget_reservation import customer_window_counters
from litellm.repositories.prisma_protocols import TableActions
from litellm.types.proxy.management_endpoints.customer_hierarchy import Budget, CustomerMember
from tests.unit.proxy.management_helpers.test_customer_hierarchy import Database, Record
NOW: Final = datetime(2026, 11, 13, 12, tzinfo=timezone.utc)
SETTINGS: Final = BudgetResetSettings(timezone="America/Los_Angeles", reset_time_of_day=time(9))
def member(member_id: str) -> CustomerMember:
return CustomerMember(
customer_member_id=member_id,
parent_org_id="org",
parent_team_ids=("team",),
spend=40,
effective_budget=Budget(
max_budget=50,
budget_duration="1mo",
budget_limits=(
BudgetLimit(budget_duration="1mo", max_budget=10),
BudgetLimit(budget_duration="12mo", max_budget=100),
),
),
created_at=NOW,
created_by="admin",
updated_at=NOW,
updated_by="admin",
)
@pytest.mark.asyncio
async def test_recorded_usage_matches_enforced_windows_and_keeps_shared_members_independent() -> None:
database: Final = Database()
first: Final = member("member-a")
second: Final = member("member-b")
counters: Final = customer_window_counters(
"customer_member", "member-a", first.effective_budget.budget_limits or (), now=NOW, reset_settings=SETTINGS
)
assert counters[0].window_start == datetime(2026, 11, 1, 17, tzinfo=timezone.utc)
database.litellm_budgetwindowspend.rows = {
"monthly": Record(
entity_type="customer_member", entity_id="member-a", window_duration="1mo",
window_start=counters[0].window_start, spend=8,
),
"yearly": Record(
entity_type="customer_member", entity_id="member-a", window_duration="12mo",
window_start=counters[1].window_start, spend=62,
),
"another-scope": Record(
entity_type="customer_team", entity_id="member-b", window_duration="1mo",
window_start=counters[0].window_start, spend=999,
),
"expired": Record(
entity_type="customer_member", entity_id="member-b", window_duration="1mo",
window_start=datetime(2026, 10, 1, 16, tzinfo=timezone.utc), spend=100,
),
}
result: Final = await customer_budget_usage(
(first, second),
cast(TableActions[LiteLLM_BudgetWindowSpend], database.litellm_budgetwindowspend),
NOW,
SETTINGS,
)
assert result[0].budget_usage is not None
assert tuple((item.spend, item.max_budget) for item in result[0].budget_usage) == ((40, 50), (8, 10), (62, 100))
assert tuple((item.window_start, item.reset_at) for item in result[0].budget_usage[1:]) == tuple(
(counter.window_start, counter.reset_at) for counter in counters
)
assert result[1].budget_usage is not None
assert tuple(item.spend for item in result[1].budget_usage) == (40, 0, 0)

View file

@ -243,6 +243,7 @@ class Database:
self.litellm_customerteamtable = Table("customer_team_id", self)
self.litellm_customermembertable = Table("customer_member_id", self)
self.litellm_budgettable = Table("budget_id", self)
self.litellm_budgetwindowspend = Table("entity_id", self)
self.litellm_verificationtoken = Table("token", self)
self.litellm_projecttable = Table("project_id", self)
self.litellm_customerbudgetincreaserequest = Table("request_id", self)