This commit is contained in:
devin-ai-integration[bot] 2026-10-28 23:30:48 +00:00 • committed by GitHub
commit 576d8c465c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
42 changed files with 2887 additions and 16 deletions

View file

@ -55,6 +55,7 @@ BACKEND_PATH_PREFIXES: tuple[str, ...] = (
"/cache_settings",
"/coordination_redis/",
"/cost_tracking",
"/subscription_accounts/",
"/cost_optimization/",
"/cost/",
"/credentials",

View file

@ -0,0 +1,19 @@
-- CreateTable
CREATE TABLE IF NOT EXISTS "LiteLLM_SubscriptionAccountTable" (
"subscription_account_id" TEXT NOT NULL,
"custom_llm_provider" TEXT NOT NULL,
"account_id" TEXT NOT NULL,
"label" TEXT,
"monthly_fee" DOUBLE PRECISION NOT NULL,
"currency" TEXT NOT NULL,
"billing_period_start" TEXT NOT NULL,
"created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
"created_by" TEXT NOT NULL,
"updated_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
"updated_by" TEXT NOT NULL,
CONSTRAINT "LiteLLM_SubscriptionAccountTable_pkey" PRIMARY KEY ("subscription_account_id")
);
-- CreateIndex
CREATE UNIQUE INDEX IF NOT EXISTS "LiteLLM_SubscriptionAccountTable_provider_account_key" ON "LiteLLM_SubscriptionAccountTable"("custom_llm_provider", "account_id");

View file

@ -2131,3 +2131,19 @@ model LiteLLM_AccountingDelivery {
@@id([event_id, target, version])
@@index([target, state, next_attempt_at])
}
model LiteLLM_SubscriptionAccountTable {
subscription_account_id String @id @default(uuid())
custom_llm_provider String
account_id String
label String?
monthly_fee Float
currency String
billing_period_start String
created_at DateTime @default(now()) @map("created_at")
created_by String
updated_at DateTime @default(now()) @updatedAt @map("updated_at")
updated_by String
@@unique([custom_llm_provider, account_id], map: "LiteLLM_SubscriptionAccountTable_provider_account_key")
}

View file

@ -886,6 +886,7 @@ PROVIDERS_THAT_AUTHENTICATE_ON_PROVIDER_INFO: Final = frozenset(
}
)
SUBSCRIPTION_BACKED_PROVIDERS: Final = frozenset({"chatgpt"})
A2A_CHAT_COMPLETION_BRIDGE_PROVIDERS: Final = frozenset({"databricks_agent"})
LITELLM_EMBEDDING_PROVIDERS_SUPPORTING_INPUT_ARRAY_OF_TOKENS: Final = [

View file

@ -361,6 +361,7 @@ _PRISMA_MODELS: Final[frozenset[str]] = frozenset(
"LiteLLM_LensReview",
"LiteLLM_LensIngestionKey",
"LiteLLM_LensWorker",
"LiteLLM_SubscriptionAccountTable",
"LiteLLM_LensSignalConfig",
"LiteLLM_LensTraceSignal",
)

View file

@ -0,0 +1,28 @@
"""
Providers whose requests are covered by a flat subscription, each with the way to read
the account id of the login a deployment is signed into.
"""
from collections.abc import Callable, Mapping
from types import MappingProxyType
from typing import Final
from litellm.llms.chatgpt.authenticator import Authenticator, get_cached_authenticator, get_chatgpt_auth_file
def _chatgpt_account_id(litellm_params: Mapping[str, object]) -> str | None:
auth_file: Final = get_chatgpt_auth_file(litellm_params)
if auth_file:
return get_cached_authenticator(auth_file).get_account_id()
api_key: Final = litellm_params.get("api_key")
return Authenticator().get_account_id(api_key if isinstance(api_key, str) and api_key else None)
SUBSCRIPTION_ACCOUNT_ID_RESOLVERS: Final[Mapping[str, Callable[[Mapping[str, object]], str | None]]] = MappingProxyType(
{"chatgpt": _chatgpt_account_id}
)
def resolve_subscription_account_id(custom_llm_provider: str, litellm_params: Mapping[str, object]) -> str | None:
resolver: Final = SUBSCRIPTION_ACCOUNT_ID_RESOLVERS.get(custom_llm_provider)
return None if resolver is None else resolver(litellm_params)

View file

@ -30,6 +30,7 @@ from litellm.models.organization_membership import LiteLLM_OrganizationMembershi
from litellm.models.project import LiteLLM_ProjectTable
from litellm.models.skills import LiteLLM_SkillsTable
from litellm.models.spend_logs import LiteLLM_ErrorLogs, LiteLLM_SpendLogs
from litellm.models.subscription_account import LiteLLM_SubscriptionAccountTable
from litellm.models.tag import LiteLLM_TagTable
from litellm.models.team import LiteLLM_TeamTable
from litellm.models.team_membership import LiteLLM_TeamMembership
@ -59,6 +60,7 @@ __all__ = [
"LiteLLM_ProxyModelTable",
"LiteLLM_SkillsTable",
"LiteLLM_SpendLogs",
"LiteLLM_SubscriptionAccountTable",
"LiteLLM_TagTable",
"LiteLLM_TeamMemberTable",
"LiteLLM_TeamMembership",

View file

@ -0,0 +1,28 @@
"""
Subscription account table model.
Canonical definition for ``litellm_subscriptionaccounttable``: the operator-entered
recurring fee of a provider account whose requests are covered by a flat subscription.
"""
from datetime import datetime
from pydantic import ConfigDict
from litellm.types.llms.base import LiteLLMPydanticObjectBase
class LiteLLM_SubscriptionAccountTable(LiteLLMPydanticObjectBase):
model_config = ConfigDict(protected_namespaces=(), frozen=True)
subscription_account_id: str
custom_llm_provider: str
account_id: str
label: str | None = None
monthly_fee: float
currency: str
billing_period_start: str
created_at: datetime
created_by: str
updated_at: datetime
updated_by: str

View file

@ -667,6 +667,11 @@ class LiteLLMRoutes(enum.Enum):
"/team/spend/by_user",
# gateway request counts (SGR); deployment-wide, admin-only
"/gateway/daily/activity",
# subscription account fees; deployment-wide, admin-only
"/subscription_accounts/usage",
"/subscription_accounts/new",
"/subscription_accounts/update",
"/subscription_accounts/delete",
# model
"/model/new",
"/model/update",

View file

@ -12,7 +12,7 @@ from typing_extensions import ReadOnly, TypedDict, assert_never
from litellm import constants
from litellm._logging import verbose_proxy_logger
from litellm.constants import PTU_SENTINEL_API_KEY
from litellm.constants import PTU_SENTINEL_API_KEY, SUBSCRIPTION_BACKED_PROVIDERS
from litellm.proxy._types import CommonProxyErrors
from litellm.proxy.spend_tracking.key_metadata_recovery import (
attach_user_details,
@ -287,6 +287,12 @@ def _entity_metadata(
return stored if stored is not None else {}
def provider_bucket_metadata(provider: str, base: Mapping[str, object]) -> Mapping[str, object]:
if provider in SUBSCRIPTION_BACKED_PROVIDERS:
return {**base, "subscription_covered": True}
return dict(base)
def update_breakdown_metrics(
breakdown: BreakdownMetrics,
record: DailySpendRecord,
@ -387,7 +393,7 @@ def update_breakdown_metrics(
if provider not in breakdown.providers:
breakdown.providers[provider] = MetricWithMetadata(
metrics=SpendMetrics(),
metadata=provider_metadata.get(provider, {}), # Add any provider-specific metadata here
metadata=provider_bucket_metadata(provider, provider_metadata.get(provider, {})),
)
breakdown.providers[provider].metrics = update_metrics(breakdown.providers[provider].metrics, record)
@ -766,12 +772,19 @@ def _aggregate_grouping_sets_records_sync(
grouped_data[date_str] = bucket
return bucket
def assign_metric_with_metadata(target: dict[str, MetricWithMetadata], key: str, metrics: SpendMetrics) -> None:
def assign_metric_with_metadata(
target: dict[str, MetricWithMetadata],
key: str,
metrics: SpendMetrics,
metadata: Mapping[str, object] | None = None,
) -> None:
existing: Final = target.get(key)
if existing is None:
target[key] = MetricWithMetadata(metrics=metrics, metadata={})
else:
existing.metrics = metrics
target[key] = MetricWithMetadata(metrics=metrics, metadata=dict(metadata or {}))
return
existing.metrics = metrics
if metadata:
existing.metadata = {**existing.metadata, **metadata}
def assign_api_key_breakdown(
target: dict[str, MetricWithMetadata],
@ -834,7 +847,9 @@ def _aggregate_grouping_sets_records_sync(
# provider the base build reported.
provider_metrics = metrics.model_copy(update={"flat_cost": 0.0})
provider = record.custom_llm_provider or "unknown"
assign_metric_with_metadata(breakdown.providers, provider, provider_metrics)
assign_metric_with_metadata(
breakdown.providers, provider, provider_metrics, provider_bucket_metadata(provider, {})
)
elif level == _GROUP_DATE_PROVIDER_API_KEY:
if record.api_key and not is_ptu_sentinel:
provider = record.custom_llm_provider or "unknown"

View file

@ -0,0 +1,311 @@
"""
Subscription accounts: the operator-entered recurring fee of a provider account whose
requests are covered by a flat subscription, shown beside metered spend on the Usage page.
"""
import re
from collections.abc import Callable, Iterable, Mapping
from dataclasses import dataclass
from datetime import date
from typing import Annotated, Final, TypeAlias
from fastapi import APIRouter, Depends, HTTPException, Query, status
from litellm.constants import LITELLM_PROXY_ADMIN_NAME, SUBSCRIPTION_BACKED_PROVIDERS
from litellm.litellm_core_utils.get_llm_provider_logic import declared_authenticating_provider
from litellm.llms.subscription_accounts import resolve_subscription_account_id
from litellm.models.subscription_account import LiteLLM_SubscriptionAccountTable
from litellm.proxy._types import CommonProxyErrors, LitellmUserRoles, UserAPIKeyAuth, user_api_key_has_admin_view
from litellm.proxy.auth.user_api_key_auth import user_api_key_auth
from litellm.proxy.spend_tracking.subscription_billing_periods import billing_periods_starting_within
from litellm.proxy.utils import get_prisma_client_or_throw
from litellm.repositories.subscription_account_repository import (
DuplicateSubscriptionAccount,
KeepLabel,
SetLabel,
SubscriptionAccountFeeChanges,
SubscriptionAccountFeeFields,
SubscriptionAccountRepository,
SubscriptionAccountStore,
)
from litellm.types.proxy.management_endpoints.subscription_accounts import (
BillingPeriod,
DeleteSubscriptionAccountRequest,
SubscriptionAccountFeeRequest,
SubscriptionAccountUsage,
SubscriptionUsageResponse,
UpdateSubscriptionAccountFeeRequest,
)
from litellm.types.router import DeploymentTypedDict
router: Final = APIRouter(prefix="/subscription_accounts", tags=["subscription accounts"])
Auth: TypeAlias = Annotated[UserAPIKeyAuth, Depends(user_api_key_auth)]
@dataclass(frozen=True, slots=True)
class SubscriptionDeployment:
model_name: str
custom_llm_provider: str
account_id: str | None
AccountIdResolver: TypeAlias = Callable[[str, Mapping[str, object]], str | None]
def _declared_provider(litellm_params: Mapping[str, object]) -> str | None:
model: Final = litellm_params.get("model")
configured_provider: Final = litellm_params.get("custom_llm_provider")
return declared_authenticating_provider(
model if isinstance(model, str) else None,
configured_provider if isinstance(configured_provider, str) else None,
)
def _subscription_deployment(
entry: DeploymentTypedDict, account_id_resolver: AccountIdResolver
) -> SubscriptionDeployment | None:
litellm_params: Final = entry["litellm_params"]
provider: Final = _declared_provider(litellm_params)
if provider is None or provider not in SUBSCRIPTION_BACKED_PROVIDERS:
return None
return SubscriptionDeployment(
model_name=entry["model_name"],
custom_llm_provider=provider,
account_id=account_id_resolver(provider, litellm_params),
)
def subscription_deployments_from_model_list(
model_list: Iterable[DeploymentTypedDict], account_id_resolver: AccountIdResolver
) -> tuple[SubscriptionDeployment, ...]:
candidates: Final = (_subscription_deployment(entry, account_id_resolver) for entry in model_list)
return tuple(candidate for candidate in candidates if candidate is not None)
def get_subscription_deployments() -> tuple[SubscriptionDeployment, ...]:
from litellm.proxy.proxy_server import llm_router
if llm_router is None:
return ()
return subscription_deployments_from_model_list(llm_router.get_model_list() or [], resolve_subscription_account_id)
def get_subscription_account_repository() -> SubscriptionAccountStore:
return SubscriptionAccountRepository(get_prisma_client_or_throw(CommonProxyErrors.db_not_connected_error.value))
Store: TypeAlias = Annotated[SubscriptionAccountStore, Depends(get_subscription_account_repository)]
Deployments: TypeAlias = Annotated[tuple[SubscriptionDeployment, ...], Depends(get_subscription_deployments)]
def _forbidden(user_api_key_dict: UserAPIKeyAuth) -> HTTPException:
return HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail={"error": f"{CommonProxyErrors.not_allowed_access.value}, your role={user_api_key_dict.user_role}"},
)
def _account_usage(
custom_llm_provider: str,
account_id: str | None,
deployments: Iterable[SubscriptionDeployment],
fee_row: LiteLLM_SubscriptionAccountTable | None,
start_date: date,
end_date: date,
) -> SubscriptionAccountUsage:
model_names: Final = tuple(sorted({deployment.model_name for deployment in deployments}))
if fee_row is None:
return SubscriptionAccountUsage(
custom_llm_provider=custom_llm_provider,
account_id=account_id,
deployments=model_names,
fee=None,
billing_periods=(),
fixed_cost=None,
)
periods: Final = billing_periods_starting_within(
date.fromisoformat(fee_row.billing_period_start), start_date, end_date
)
return SubscriptionAccountUsage(
custom_llm_provider=custom_llm_provider,
account_id=account_id,
deployments=model_names,
fee=fee_row,
billing_periods=tuple(BillingPeriod(start=period.start, end=period.end) for period in periods),
fixed_cost=len(periods) * fee_row.monthly_fee,
)
def build_subscription_usage(
deployments: Iterable[SubscriptionDeployment],
fee_rows: Iterable[LiteLLM_SubscriptionAccountTable],
start_date: date,
end_date: date,
) -> SubscriptionUsageResponse:
deployment_tuple: Final = tuple(deployments)
fees_by_account: Final = {(row.custom_llm_provider, row.account_id): row for row in fee_rows}
deployment_keys: Final = {(d.custom_llm_provider, d.account_id) for d in deployment_tuple}
account_keys: Final = sorted(deployment_keys | set(fees_by_account), key=lambda key: (key[0], key[1] or "~"))
accounts: Final = tuple(
_account_usage(
provider,
account_id,
(d for d in deployment_tuple if (d.custom_llm_provider, d.account_id) == (provider, account_id)),
fees_by_account.get((provider, account_id)) if account_id is not None else None,
start_date,
end_date,
)
for provider, account_id in account_keys
)
return SubscriptionUsageResponse(
start_date=start_date,
end_date=end_date,
subscription_providers=tuple(sorted(SUBSCRIPTION_BACKED_PROVIDERS)),
accounts=accounts,
)
_DAY_PATTERN: Final = re.compile(r"\d{4}-\d{2}-\d{2}")
def _parse_day(value: str) -> date | None:
if _DAY_PATTERN.fullmatch(value) is None:
return None
try:
return date.fromisoformat(value)
except ValueError:
return None
def _parse_date(value: str, name: str) -> date:
parsed: Final = _parse_day(value)
if parsed is None:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST, detail={"error": f"{name} must be YYYY-MM-DD, got {value!r}"}
)
return parsed
@router.get("/usage", response_model=SubscriptionUsageResponse, dependencies=[Depends(user_api_key_auth)])
async def get_subscription_usage(
start_date: Annotated[str, Query(description="First day of the Usage page filter, YYYY-MM-DD")],
end_date: Annotated[str, Query(description="Last day of the Usage page filter, YYYY-MM-DD")],
user_api_key_dict: Auth,
repository: Store,
deployments: Deployments,
) -> SubscriptionUsageResponse:
"""
Subscription-backed accounts behind the proxy's deployments, each with its configured
monthly fee and the fixed cost attributed to the date range: the fee once per billing
period whose start date falls inside the range, however many deployments share the account.
"""
if not user_api_key_has_admin_view(user_api_key_dict):
raise _forbidden(user_api_key_dict)
start: Final = _parse_date(start_date, "start_date")
end: Final = _parse_date(end_date, "end_date")
if end < start:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST, detail={"error": "end_date must not be before start_date"}
)
return build_subscription_usage(deployments, await repository.list_all(), start, end)
def _require_proxy_admin(user_api_key_dict: UserAPIKeyAuth) -> None:
if user_api_key_dict.user_role != LitellmUserRoles.PROXY_ADMIN:
raise _forbidden(user_api_key_dict)
def _actor(user_api_key_dict: UserAPIKeyAuth) -> str:
return user_api_key_dict.user_id or LITELLM_PROXY_ADMIN_NAME
@router.post("/new", response_model=LiteLLM_SubscriptionAccountTable, dependencies=[Depends(user_api_key_auth)])
async def new_subscription_account(
request: SubscriptionAccountFeeRequest,
user_api_key_dict: Auth,
repository: Store,
) -> LiteLLM_SubscriptionAccountTable:
"""Record the monthly fee of one subscription-backed provider account."""
_require_proxy_admin(user_api_key_dict)
if request.custom_llm_provider not in SUBSCRIPTION_BACKED_PROVIDERS:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail={
"error": f"{request.custom_llm_provider!r} is not a subscription-backed provider; "
f"expected one of {sorted(SUBSCRIPTION_BACKED_PROVIDERS)}"
},
)
created: Final = await repository.create_account(
request.custom_llm_provider,
request.account_id,
SubscriptionAccountFeeFields(
monthly_fee=request.monthly_fee,
currency=request.currency,
billing_period_start=request.billing_period_start.isoformat(),
label=request.label,
),
_actor(user_api_key_dict),
)
if isinstance(created, DuplicateSubscriptionAccount):
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail={
"error": f"A fee is already configured for {created.custom_llm_provider} account "
f"{created.account_id}; use /subscription_accounts/update to change it"
},
)
return created
def _fee_changes(request: UpdateSubscriptionAccountFeeRequest) -> SubscriptionAccountFeeChanges:
return SubscriptionAccountFeeChanges(
monthly_fee=request.monthly_fee,
currency=request.currency,
billing_period_start=(
request.billing_period_start.isoformat() if request.billing_period_start is not None else None
),
label=SetLabel(request.label) if "label" in request.model_fields_set else KeepLabel(),
)
@router.post("/update", response_model=LiteLLM_SubscriptionAccountTable, dependencies=[Depends(user_api_key_auth)])
async def update_subscription_account(
request: UpdateSubscriptionAccountFeeRequest,
user_api_key_dict: Auth,
repository: Store,
) -> LiteLLM_SubscriptionAccountTable:
"""
Change the fee, currency, billing period start, or label of a subscription account.
Only the fields named in the request are written, so two admins changing different
fields at the same time both land.
"""
_require_proxy_admin(user_api_key_dict)
updated: Final = await repository.update_fee(
request.subscription_account_id, _fee_changes(request), _actor(user_api_key_dict)
)
if updated is None:
raise _not_found(request.subscription_account_id)
return updated
@router.post("/delete", response_model=LiteLLM_SubscriptionAccountTable, dependencies=[Depends(user_api_key_auth)])
async def delete_subscription_account(
request: DeleteSubscriptionAccountRequest,
user_api_key_dict: Auth,
repository: Store,
) -> LiteLLM_SubscriptionAccountTable:
"""Stop tracking a subscription account's fee; its requests stay marked as subscription-covered."""
_require_proxy_admin(user_api_key_dict)
if await repository.find_by_id(request.subscription_account_id) is None:
raise _not_found(request.subscription_account_id)
deleted: Final = await repository.delete_account(request.subscription_account_id)
if deleted is None:
raise _not_found(request.subscription_account_id)
return deleted
def _not_found(subscription_account_id: str) -> HTTPException:
return HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail={"error": f"No subscription account with id {subscription_account_id}"},
)

View file

@ -765,6 +765,9 @@ from litellm.proxy.management_endpoints.session_endpoints import (
router as session_management_router,
)
from litellm.proxy.management_endpoints.sso.saml_sso import SAML_AUTHN_REQUEST_TTL_SECONDS
from litellm.proxy.management_endpoints.subscription_accounts import (
router as subscription_accounts_router,
)
from litellm.proxy.management_endpoints.tag_management_endpoints import (
router as tag_management_router,
)
@ -21726,6 +21729,7 @@ app.include_router(memory_router)
app.include_router(lens_router)
app.include_router(plugin_router)
app.include_router(cost_tracking_settings_router)
app.include_router(subscription_accounts_router)
app.include_router(prompt_caching_requests_router)
app.include_router(router_settings_router)
app.include_router(fallback_management_router)

View file

@ -2131,3 +2131,19 @@ model LiteLLM_AccountingDelivery {
@@id([event_id, target, version])
@@index([target, state, next_attempt_at])
}
model LiteLLM_SubscriptionAccountTable {
subscription_account_id String @id @default(uuid())
custom_llm_provider String
account_id String
label String?
monthly_fee Float
currency String
billing_period_start String
created_at DateTime @default(now()) @map("created_at")
created_by String
updated_at DateTime @default(now()) @updatedAt @map("updated_at")
updated_by String
@@unique([custom_llm_provider, account_id], map: "LiteLLM_SubscriptionAccountTable_provider_account_key")
}

View file

@ -0,0 +1,54 @@
from calendar import monthrange
from dataclasses import dataclass
from datetime import date, timedelta
from typing import Final
@dataclass(frozen=True, slots=True)
class BillingPeriodRange:
start: date
end: date
def _month_index(anchor: date, months_after_anchor: int) -> int:
return anchor.year * 12 + (anchor.month - 1) + months_after_anchor
_LAST_MONTH_INDEX: Final = _month_index(date.max, 0)
def _month_start(anchor: date, months_after_anchor: int) -> date:
month_index: Final = _month_index(anchor, months_after_anchor)
year: Final = month_index // 12
month: Final = month_index % 12 + 1
return date(year, month, min(anchor.day, monthrange(year, month)[1]))
def _period_end(anchor: date, months_after_anchor: int) -> date:
if _month_index(anchor, months_after_anchor + 1) > _LAST_MONTH_INDEX:
return date.max
return _month_start(anchor, months_after_anchor + 1) - timedelta(days=1)
def _first_candidate_index(anchor: date, start_date: date) -> int:
months_apart: Final = (start_date.year - anchor.year) * 12 + (start_date.month - anchor.month)
return max(0, months_apart - 1)
def billing_periods_starting_within(anchor: date, start_date: date, end_date: date) -> tuple[BillingPeriodRange, ...]:
"""Monthly periods anchored on `anchor`'s day of month whose start lies inside [start_date, end_date]."""
if end_date < start_date or end_date < anchor:
return ()
first_index: Final = _first_candidate_index(anchor, start_date)
last_index: Final = min(
first_index + _month_span(start_date, end_date) + 1, _LAST_MONTH_INDEX - _month_index(anchor, 0)
)
candidates: Final = (
BillingPeriodRange(start=_month_start(anchor, index), end=_period_end(anchor, index))
for index in range(first_index, last_index + 1)
)
return tuple(period for period in candidates if start_date <= period.start <= end_date)
def _month_span(start_date: date, end_date: date) -> int:
return (end_date.year - start_date.year) * 12 + (end_date.month - start_date.month)

View file

@ -0,0 +1,134 @@
"""
Subscription account repository for database operations on LiteLLM_SubscriptionAccountTable.
"""
from collections.abc import Mapping
from dataclasses import dataclass
from types import MappingProxyType
from typing import TYPE_CHECKING, Final, Protocol, TypeAlias
from litellm.models.subscription_account import LiteLLM_SubscriptionAccountTable
from litellm.repositories.base_repository import BaseRepository, is_unique_violation
from litellm.repositories.prisma_protocols import TableActions
from litellm.repositories.table_repositories import PrismaTableRepository
if TYPE_CHECKING:
from prisma import models as prisma_models
@dataclass(frozen=True, slots=True)
class DuplicateSubscriptionAccount:
custom_llm_provider: str
account_id: str
@dataclass(frozen=True, slots=True)
class SubscriptionAccountFeeFields:
monthly_fee: float
currency: str
billing_period_start: str
label: str | None
@dataclass(frozen=True, slots=True)
class KeepLabel:
pass
@dataclass(frozen=True, slots=True)
class SetLabel:
value: str | None
LabelChange: TypeAlias = KeepLabel | SetLabel
@dataclass(frozen=True, slots=True)
class SubscriptionAccountFeeChanges:
monthly_fee: float | None = None
currency: str | None = None
billing_period_start: str | None = None
label: LabelChange = KeepLabel()
def columns(self) -> Mapping[str, float | str | None]:
named: Final = {
"monthly_fee": self.monthly_fee,
"currency": self.currency,
"billing_period_start": self.billing_period_start,
}
present: Final = {column: value for column, value in named.items() if value is not None}
label_column: Final = {"label": self.label.value} if isinstance(self.label, SetLabel) else {}
return MappingProxyType({**present, **label_column})
class SubscriptionAccountStore(Protocol):
async def list_all(self) -> tuple[LiteLLM_SubscriptionAccountTable, ...]: ...
async def find_by_id(self, id_value: str) -> LiteLLM_SubscriptionAccountTable | None: ...
async def create_account(
self, custom_llm_provider: str, account_id: str, fee: SubscriptionAccountFeeFields, created_by: str
) -> LiteLLM_SubscriptionAccountTable | DuplicateSubscriptionAccount: ...
async def update_fee(
self, subscription_account_id: str, changes: SubscriptionAccountFeeChanges, updated_by: str
) -> LiteLLM_SubscriptionAccountTable | None: ...
async def delete_account(self, subscription_account_id: str) -> LiteLLM_SubscriptionAccountTable | None: ...
class _SubscriptionAccountTable(PrismaTableRepository["prisma_models.LiteLLM_SubscriptionAccountTable"]):
table_name = "litellm_subscriptionaccounttable"
class SubscriptionAccountRepository(BaseRepository[LiteLLM_SubscriptionAccountTable]):
def __init__(self, prisma_client: object) -> None:
super().__init__(prisma_client)
self._table: Final = _SubscriptionAccountTable(prisma_client)
@property
def table(self) -> TableActions["prisma_models.LiteLLM_SubscriptionAccountTable"]:
return self._table.table
@property
def model_class(self) -> type[LiteLLM_SubscriptionAccountTable]:
return LiteLLM_SubscriptionAccountTable
async def list_all(self) -> tuple[LiteLLM_SubscriptionAccountTable, ...]:
return tuple(await self.find_many(order={"created_at": "asc"}))
async def find_by_id(
self, id_value: str, id_field: str = "subscription_account_id"
) -> LiteLLM_SubscriptionAccountTable | None:
return await super().find_by_id(id_value, id_field)
async def create_account(
self, custom_llm_provider: str, account_id: str, fee: SubscriptionAccountFeeFields, created_by: str
) -> LiteLLM_SubscriptionAccountTable | DuplicateSubscriptionAccount:
try:
return await self.create(
{
"custom_llm_provider": custom_llm_provider,
"account_id": account_id,
"monthly_fee": fee.monthly_fee,
"currency": fee.currency,
"billing_period_start": fee.billing_period_start,
"label": fee.label,
"created_by": created_by,
"updated_by": created_by,
}
)
except Exception as exc:
if is_unique_violation(exc):
return DuplicateSubscriptionAccount(custom_llm_provider=custom_llm_provider, account_id=account_id)
raise
async def update_fee(
self, subscription_account_id: str, changes: SubscriptionAccountFeeChanges, updated_by: str
) -> LiteLLM_SubscriptionAccountTable | None:
return await self.update(
subscription_account_id, {**changes.columns(), "updated_by": updated_by}, id_field="subscription_account_id"
)
async def delete_account(self, subscription_account_id: str) -> LiteLLM_SubscriptionAccountTable | None:
return await self.delete(subscription_account_id, id_field="subscription_account_id")

View file

@ -0,0 +1,62 @@
from datetime import date
from typing import Final
from pydantic import BaseModel, ConfigDict, Field
from litellm.models.subscription_account import LiteLLM_SubscriptionAccountTable
CURRENCY_CODE_PATTERN: Final = r"^[A-Z]{3}$"
class SubscriptionAccountFeeRequest(BaseModel):
model_config = ConfigDict(frozen=True)
custom_llm_provider: str = Field(min_length=1)
account_id: str = Field(min_length=1)
monthly_fee: float = Field(gt=0)
currency: str = Field(pattern=CURRENCY_CODE_PATTERN)
billing_period_start: date
label: str | None = None
class UpdateSubscriptionAccountFeeRequest(BaseModel):
model_config = ConfigDict(frozen=True)
subscription_account_id: str
monthly_fee: float | None = Field(default=None, gt=0)
currency: str | None = Field(default=None, pattern=CURRENCY_CODE_PATTERN)
billing_period_start: date | None = None
label: str | None = None
class DeleteSubscriptionAccountRequest(BaseModel):
model_config = ConfigDict(frozen=True)
subscription_account_id: str
class BillingPeriod(BaseModel):
model_config = ConfigDict(frozen=True)
start: date
end: date
class SubscriptionAccountUsage(BaseModel):
model_config = ConfigDict(frozen=True)
custom_llm_provider: str
account_id: str | None
deployments: tuple[str, ...]
fee: LiteLLM_SubscriptionAccountTable | None
billing_periods: tuple[BillingPeriod, ...]
fixed_cost: float | None
class SubscriptionUsageResponse(BaseModel):
model_config = ConfigDict(frozen=True)
start_date: date
end_date: date
subscription_providers: tuple[str, ...]
accounts: tuple[SubscriptionAccountUsage, ...]

View file

@ -2131,3 +2131,19 @@ model LiteLLM_AccountingDelivery {
@@id([event_id, target, version])
@@index([target, state, next_attempt_at])
}
model LiteLLM_SubscriptionAccountTable {
subscription_account_id String @id @default(uuid())
custom_llm_provider String
account_id String
label String?
monthly_fee Float
currency String
billing_period_start String
created_at DateTime @default(now()) @map("created_at")
created_by String
updated_at DateTime @default(now()) @updatedAt @map("updated_at")
updated_by String
@@unique([custom_llm_provider, account_id], map: "LiteLLM_SubscriptionAccountTable_provider_account_key")
}

View file

@ -0,0 +1,65 @@
import base64
import json
from pathlib import Path
from typing import Final
import pytest
from litellm.constants import SUBSCRIPTION_BACKED_PROVIDERS
from litellm.llms.chatgpt.common_utils import OPENAI_AUTH_CLAIM_KEY
from litellm.llms.subscription_accounts import SUBSCRIPTION_ACCOUNT_ID_RESOLVERS, resolve_subscription_account_id
def _write_login(path: Path, account_id: str) -> Path:
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(json.dumps({"account_id": account_id}))
return path
def _access_token_for(account_id: str) -> str:
claims: Final = json.dumps({OPENAI_AUTH_CLAIM_KEY: {"chatgpt_account_id": account_id}}).encode()
payload: Final = base64.urlsafe_b64encode(claims).decode().rstrip("=")
return f"header.{payload}.signature"
@pytest.fixture
def signed_in_chatgpt_token_dir(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
monkeypatch.setenv("CHATGPT_TOKEN_DIR", str(tmp_path))
monkeypatch.delenv("CHATGPT_AUTH_FILE", raising=False)
_write_login(tmp_path / "auth.json", "acct-from-token-file")
return tmp_path
def test_every_subscription_backed_provider_has_an_account_id_resolver() -> None:
assert frozenset(SUBSCRIPTION_ACCOUNT_ID_RESOLVERS) == SUBSCRIPTION_BACKED_PROVIDERS
def test_chatgpt_resolves_to_the_account_in_the_signed_in_token_file(signed_in_chatgpt_token_dir: Path) -> None:
assert resolve_subscription_account_id("chatgpt", {"model": "chatgpt/gpt-5.6-terra"}) == "acct-from-token-file"
def test_each_deployment_takes_the_account_of_its_own_auth_file(signed_in_chatgpt_token_dir: Path) -> None:
first: Final = _write_login(signed_in_chatgpt_token_dir / "team-a" / "auth.json", "acct-team-a")
second: Final = _write_login(signed_in_chatgpt_token_dir / "team-b" / "auth.json", "acct-team-b")
assert resolve_subscription_account_id("chatgpt", {"chatgpt_auth_file": str(first)}) == "acct-team-a"
assert resolve_subscription_account_id("chatgpt", {"chatgpt_auth_file": str(second)}) == "acct-team-b"
def test_a_configured_access_token_resolves_to_its_own_account(signed_in_chatgpt_token_dir: Path) -> None:
litellm_params: Final = {"model": "chatgpt/gpt-5.6-terra", "api_key": _access_token_for("acct-from-api-key")}
assert resolve_subscription_account_id("chatgpt", litellm_params) == "acct-from-api-key"
def test_a_metered_provider_resolves_to_no_account_even_with_a_chatgpt_login(
signed_in_chatgpt_token_dir: Path,
) -> None:
assert resolve_subscription_account_id("openai", {"model": "openai/gpt-5.6-terra"}) is None
def test_chatgpt_without_a_login_resolves_to_no_account(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
empty_dir: Final = tmp_path / "no-login"
monkeypatch.setenv("CHATGPT_TOKEN_DIR", str(empty_dir))
monkeypatch.delenv("CHATGPT_AUTH_FILE", raising=False)
assert resolve_subscription_account_id("chatgpt", {"model": "chatgpt/gpt-5.6-terra"}) is None

View file

@ -2551,3 +2551,68 @@ async def test_get_daily_activity_rejects_non_canonical_dates_before_querying(st
assert error.value.detail == {"error": "start_date and end_date must be valid YYYY-MM-DD dates"}
mock_table.count.assert_not_awaited()
mock_table.find_many.assert_not_awaited()
def _provider_record(provider: str, *, model: str, spend: float):
base = vars(_spend_record("real-key", model=model, spend=spend))
return SimpleNamespace(**{**base, "custom_llm_provider": provider, "api_requests": 1, "successful_requests": 1})
def test_per_row_provider_bucket_marks_subscription_backed_providers_only():
from litellm.proxy.management_endpoints.common_daily_activity import update_breakdown_metrics
from litellm.types.proxy.management_endpoints.common_daily_activity import BreakdownMetrics
breakdown = BreakdownMetrics()
update_breakdown_metrics(breakdown, _provider_record("chatgpt", model="gpt-5.6-terra", spend=0.0), {}, {}, {})
update_breakdown_metrics(breakdown, _provider_record("openai", model="gpt-5.6", spend=0.0), {}, {}, {})
update_breakdown_metrics(breakdown, _provider_record("chatgpt", model="gpt-5.6-sol", spend=0.0), {}, {}, {})
assert breakdown.providers["chatgpt"].metadata == {"subscription_covered": True}
assert "subscription_covered" not in breakdown.providers["openai"].metadata
assert breakdown.providers["chatgpt"].metrics.api_requests == 2
assert "subscription_covered" not in breakdown.models["gpt-5.6-terra"].metadata
def test_per_row_provider_marker_keeps_existing_provider_metadata():
from litellm.proxy.management_endpoints.common_daily_activity import update_breakdown_metrics
from litellm.types.proxy.management_endpoints.common_daily_activity import BreakdownMetrics
breakdown = BreakdownMetrics()
update_breakdown_metrics(
breakdown,
_provider_record("chatgpt", model="gpt-5.6-terra", spend=0.0),
{},
{"chatgpt": {"region": "us"}},
{},
)
assert breakdown.providers["chatgpt"].metadata == {"region": "us", "subscription_covered": True}
@pytest.mark.parametrize("provider_row_first", [True, False])
def test_grouping_sets_provider_bucket_marks_subscription_backed_providers_in_any_row_order(provider_row_first):
from litellm.proxy.management_endpoints.common_daily_activity import (
_GROUP_DATE_PROVIDER,
_GROUP_DATE_PROVIDER_API_KEY,
_GROUP_GRAND_TOTAL,
_aggregate_grouping_sets_records_sync,
)
provider_rows = [
_grouping_row(_GROUP_DATE_PROVIDER, custom_llm_provider="chatgpt", spend=0.0),
_grouping_row(_GROUP_DATE_PROVIDER_API_KEY, custom_llm_provider="chatgpt", api_key="real-key", spend=0.0),
]
ordered_rows = provider_rows if provider_row_first else list(reversed(provider_rows))
records = [
*ordered_rows,
_grouping_row(_GROUP_DATE_PROVIDER, custom_llm_provider="openai", spend=0.0),
_grouping_row(_GROUP_DATE_PROVIDER_API_KEY, custom_llm_provider="openai", api_key="real-key", spend=0.0),
_grouping_row(_GROUP_GRAND_TOTAL, spend=0.0),
]
aggregated = _aggregate_grouping_sets_records_sync(records=records, api_key_metadata={})
providers = aggregated["results"][0].breakdown.providers
assert providers["chatgpt"].metadata == {"subscription_covered": True}
assert "real-key" in providers["chatgpt"].api_key_breakdown
assert "subscription_covered" not in providers["openai"].metadata

View file

@ -0,0 +1,393 @@
from collections.abc import Iterator
from datetime import datetime, timezone
from typing import Final
from uuid import uuid4
from unittest.mock import MagicMock
import pytest
from fastapi import FastAPI, HTTPException, Request
from fastapi.testclient import TestClient
from litellm.models.subscription_account import LiteLLM_SubscriptionAccountTable
from litellm.proxy._types import LiteLLM_JWTAuth, LitellmUserRoles, UserAPIKeyAuth
from litellm.proxy.auth.auth_checks import allowed_routes_check
from litellm.proxy.auth.route_checks import RouteChecks
from litellm.proxy.auth.user_api_key_auth import user_api_key_auth
from litellm.proxy.management_endpoints.subscription_accounts import (
SubscriptionDeployment,
get_subscription_account_repository,
get_subscription_deployments,
router,
subscription_deployments_from_model_list,
)
from litellm.repositories.subscription_account_repository import (
DuplicateSubscriptionAccount,
SubscriptionAccountFeeChanges,
SubscriptionAccountFeeFields,
)
_ACCOUNT: Final = "org-team-workspace"
_TEST_FEE: Final = {
"custom_llm_provider": "chatgpt",
"account_id": _ACCOUNT,
"monthly_fee": 25.0,
"currency": "USD",
"billing_period_start": "2026-10-01",
"label": "Team plan (test value)",
}
_TWO_DEPLOYMENTS_ONE_ACCOUNT: Final = (
SubscriptionDeployment(model_name="gpt-5.6-terra", custom_llm_provider="chatgpt", account_id=_ACCOUNT),
SubscriptionDeployment(model_name="gpt-5.6-sol", custom_llm_provider="chatgpt", account_id=_ACCOUNT),
)
class _FakeStore:
def __init__(self) -> None:
self.rows: dict[str, LiteLLM_SubscriptionAccountTable] = {}
self.written_columns: list[dict[str, float | str | None]] = []
async def list_all(self) -> list[LiteLLM_SubscriptionAccountTable]:
return sorted(self.rows.values(), key=lambda row: row.created_at)
async def find_by_id(self, id_value: str) -> LiteLLM_SubscriptionAccountTable | None:
return self.rows.get(id_value)
async def create_account(
self, custom_llm_provider: str, account_id: str, fee: SubscriptionAccountFeeFields, created_by: str
) -> LiteLLM_SubscriptionAccountTable | DuplicateSubscriptionAccount:
for row in self.rows.values():
if (row.custom_llm_provider, row.account_id) == (custom_llm_provider, account_id):
return DuplicateSubscriptionAccount(custom_llm_provider=custom_llm_provider, account_id=account_id)
now = datetime.now(timezone.utc)
row = LiteLLM_SubscriptionAccountTable(
subscription_account_id=str(uuid4()),
custom_llm_provider=custom_llm_provider,
account_id=account_id,
label=fee.label,
monthly_fee=fee.monthly_fee,
currency=fee.currency,
billing_period_start=fee.billing_period_start,
created_at=now,
created_by=created_by,
updated_at=now,
updated_by=created_by,
)
self.rows[row.subscription_account_id] = row
return row
async def update_fee(
self, subscription_account_id: str, changes: SubscriptionAccountFeeChanges, updated_by: str
) -> LiteLLM_SubscriptionAccountTable | None:
columns = dict(changes.columns())
self.written_columns.append(columns)
existing = self.rows.get(subscription_account_id)
if existing is None:
return None
updated = existing.model_copy(
update={**columns, "updated_by": updated_by, "updated_at": datetime.now(timezone.utc)}
)
self.rows[subscription_account_id] = updated
return updated
async def delete_account(self, subscription_account_id: str) -> LiteLLM_SubscriptionAccountTable | None:
return self.rows.pop(subscription_account_id, None)
def _resolve_auth(request: Request) -> UserAPIKeyAuth:
role: Final = LitellmUserRoles(request.headers.get("x-user-role", LitellmUserRoles.PROXY_ADMIN.value))
return UserAPIKeyAuth(user_id="admin", user_role=role, api_key="sk-test")
@pytest.fixture
def deployments() -> tuple[SubscriptionDeployment, ...]:
return _TWO_DEPLOYMENTS_ONE_ACCOUNT
@pytest.fixture
def client(deployments: tuple[SubscriptionDeployment, ...]) -> Iterator[tuple[TestClient, _FakeStore]]:
store: Final = _FakeStore()
app: Final = FastAPI()
app.include_router(router)
app.dependency_overrides[get_subscription_account_repository] = lambda: store
app.dependency_overrides[get_subscription_deployments] = lambda: deployments
app.dependency_overrides[user_api_key_auth] = _resolve_auth
with TestClient(app) as test_client:
yield test_client, store
def _usage(test_client: TestClient, start_date: str, end_date: str, **headers: str) -> dict:
response = test_client.get(
"/subscription_accounts/usage", params={"start_date": start_date, "end_date": end_date}, headers=headers
)
assert response.status_code == 200, response.text
return response.json()
def test_untracked_account_lists_its_deployments_with_no_fee(client):
test_client, _ = client
body = _usage(test_client, "2026-10-01", "2026-10-07")
assert body["subscription_providers"] == ["chatgpt"]
assert body["accounts"] == [
{
"custom_llm_provider": "chatgpt",
"account_id": _ACCOUNT,
"deployments": ["gpt-5.6-sol", "gpt-5.6-terra"],
"fee": None,
"billing_periods": [],
"fixed_cost": None,
}
]
def test_fee_counts_once_per_billing_period_however_many_deployments_share_the_account(client):
test_client, _ = client
created = test_client.post("/subscription_accounts/new", json=_TEST_FEE)
assert created.status_code == 200, created.text
one_period = _usage(test_client, "2026-10-01", "2026-10-07")
two_periods = _usage(test_client, "2026-09-15", "2026-11-15")
between_starts = _usage(test_client, "2026-10-02", "2026-10-31")
(account,) = one_period["accounts"]
assert account["deployments"] == ["gpt-5.6-sol", "gpt-5.6-terra"]
assert account["fee"]["monthly_fee"] == 25.0
assert account["fee"]["currency"] == "USD"
assert account["fee"]["label"] == "Team plan (test value)"
assert account["billing_periods"] == [{"start": "2026-10-01", "end": "2026-10-31"}]
assert account["fixed_cost"] == 25.0
assert two_periods["accounts"][0]["fixed_cost"] == 50.0
assert [period["start"] for period in two_periods["accounts"][0]["billing_periods"]] == [
"2026-10-01",
"2026-11-01",
]
assert between_starts["accounts"][0]["fixed_cost"] == 0.0
assert between_starts["accounts"][0]["billing_periods"] == []
def test_fee_without_a_matching_deployment_is_still_listed(client):
test_client, _ = client
other = {**_TEST_FEE, "account_id": "org-other", "monthly_fee": 200.0, "currency": "EUR"}
assert test_client.post("/subscription_accounts/new", json=other).status_code == 200
body = _usage(test_client, "2026-10-01", "2026-10-07")
assert [account["account_id"] for account in body["accounts"]] == ["org-other", _ACCOUNT]
assert body["accounts"][0]["deployments"] == []
assert body["accounts"][0]["fee"]["currency"] == "EUR"
assert body["accounts"][0]["fixed_cost"] == 200.0
assert body["accounts"][1]["fee"] is None
@pytest.mark.parametrize(
"deployments",
[(SubscriptionDeployment(model_name="gpt-5.6-terra", custom_llm_provider="chatgpt", account_id=None),)],
)
def test_account_not_signed_in_shows_no_account_and_takes_no_fee(client):
test_client, _ = client
assert test_client.post("/subscription_accounts/new", json=_TEST_FEE).status_code == 200
body = _usage(test_client, "2026-10-01", "2026-10-07")
unsigned = next(account for account in body["accounts"] if account["account_id"] is None)
assert unsigned["deployments"] == ["gpt-5.6-terra"]
assert unsigned["fee"] is None
assert unsigned["fixed_cost"] is None
def test_update_changes_the_fee_and_delete_returns_the_account_to_untracked(client):
test_client, store = client
created = test_client.post("/subscription_accounts/new", json=_TEST_FEE).json()
account_id = created["subscription_account_id"]
updated = test_client.post(
"/subscription_accounts/update",
json={"subscription_account_id": account_id, "monthly_fee": 30.0, "billing_period_start": "2026-10-05"},
)
assert updated.status_code == 200, updated.text
assert updated.json()["monthly_fee"] == 30.0
assert updated.json()["currency"] == "USD"
assert updated.json()["billing_period_start"] == "2026-10-05"
assert updated.json()["label"] == _TEST_FEE["label"]
assert _usage(test_client, "2026-10-01", "2026-10-07")["accounts"][0]["fixed_cost"] == 30.0
cleared = test_client.post(
"/subscription_accounts/update", json={"subscription_account_id": account_id, "label": None}
)
assert cleared.status_code == 200, cleared.text
assert cleared.json()["label"] is None
assert cleared.json()["monthly_fee"] == 30.0
assert store.written_columns == [{"monthly_fee": 30.0, "billing_period_start": "2026-10-05"}, {"label": None}]
unknown = test_client.post(
"/subscription_accounts/update", json={"subscription_account_id": "no-such-account", "monthly_fee": 1.0}
)
assert unknown.status_code == 404
deleted = test_client.post("/subscription_accounts/delete", json={"subscription_account_id": account_id})
assert deleted.status_code == 200, deleted.text
assert store.rows == {}
assert _usage(test_client, "2026-10-01", "2026-10-07")["accounts"][0]["fixed_cost"] is None
missing = test_client.post("/subscription_accounts/delete", json={"subscription_account_id": account_id})
assert missing.status_code == 404
def test_rejects_a_second_fee_for_the_same_account(client):
test_client, _ = client
assert test_client.post("/subscription_accounts/new", json=_TEST_FEE).status_code == 200
duplicate = test_client.post("/subscription_accounts/new", json={**_TEST_FEE, "monthly_fee": 99.0})
assert duplicate.status_code == 400
assert "/subscription_accounts/update" in duplicate.json()["detail"]["error"]
def test_rejects_a_fee_on_a_metered_provider(client):
test_client, store = client
response = test_client.post("/subscription_accounts/new", json={**_TEST_FEE, "custom_llm_provider": "openai"})
assert response.status_code == 400
assert store.rows == {}
@pytest.mark.parametrize(
"payload",
[
{**_TEST_FEE, "monthly_fee": 0},
{**_TEST_FEE, "account_id": ""},
{**_TEST_FEE, "currency": "usd"},
{**_TEST_FEE, "currency": "$"},
{**_TEST_FEE, "billing_period_start": "10/01/2026"},
],
)
def test_rejects_malformed_fee_fields(client, payload):
test_client, store = client
assert test_client.post("/subscription_accounts/new", json=payload).status_code == 422
assert store.rows == {}
def test_usage_rejects_a_malformed_or_inverted_range(client):
test_client, _ = client
malformed = [
test_client.get("/subscription_accounts/usage", params={"start_date": start, "end_date": "2026-10-07"})
for start in ("2026-10-1", "20261001", "2026-W40-1", "2026-13-01")
]
inverted = test_client.get(
"/subscription_accounts/usage", params={"start_date": "2026-10-07", "end_date": "2026-10-01"}
)
assert [response.status_code for response in malformed] == [400, 400, 400, 400]
assert inverted.status_code == 400
def test_viewer_reads_usage_but_cannot_write(client):
test_client, store = client
viewer = {"x-user-role": LitellmUserRoles.PROXY_ADMIN_VIEW_ONLY.value}
assert _usage(test_client, "2026-10-01", "2026-10-07", **viewer)["accounts"][0]["account_id"] == _ACCOUNT
assert test_client.post("/subscription_accounts/new", json=_TEST_FEE, headers=viewer).status_code == 403
assert store.rows == {}
_SUBSCRIPTION_ROUTES: Final = (
"/subscription_accounts/usage",
"/subscription_accounts/new",
"/subscription_accounts/update",
"/subscription_accounts/delete",
)
def test_routes_follow_the_admin_route_policy():
jwt_admin_defaults = LiteLLM_JWTAuth()
for route in _SUBSCRIPTION_ROUTES:
assert allowed_routes_check(
user_role=LitellmUserRoles.PROXY_ADMIN, user_route=route, litellm_proxy_roles=jwt_admin_defaults
)
assert RouteChecks.is_management_route(route)
def test_viewer_route_gate_reads_usage_and_blocks_writes():
viewer_role: Final = LitellmUserRoles.PROXY_ADMIN_VIEW_ONLY.value
get_usage = MagicMock(spec=Request, method="GET", query_params={})
post_new = MagicMock(spec=Request, method="POST", query_params={})
RouteChecks._check_proxy_admin_viewer_access(
route="/subscription_accounts/usage", _user_role=viewer_role, request_data={}, request=get_usage
)
with pytest.raises(HTTPException) as denied:
RouteChecks._check_proxy_admin_viewer_access(
route="/subscription_accounts/new", _user_role=viewer_role, request_data=_TEST_FEE, request=post_new
)
assert denied.value.status_code == 403
def test_internal_user_cannot_read_subscription_accounts(client):
test_client, _ = client
response = test_client.get(
"/subscription_accounts/usage",
params={"start_date": "2026-10-01", "end_date": "2026-10-07"},
headers={"x-user-role": LitellmUserRoles.INTERNAL_USER.value},
)
assert response.status_code == 403
def test_deployments_take_the_account_of_their_own_login():
model_list = [
{"model_name": "gpt-5.6-terra", "litellm_params": {"model": "chatgpt/gpt-5.6-terra"}},
{"model_name": "gpt-5.6-sol", "litellm_params": {"model": "chatgpt/gpt-5.6-sol"}},
{
"model_name": "gpt-5.6-luna",
"litellm_params": {"model": "chatgpt/gpt-5.6-luna", "chatgpt_auth_file": "/logins/other.json"},
},
{"model_name": "sonnet", "litellm_params": {"model": "anthropic/claude-sonnet-4-5", "api_key": "sk-x"}},
{"model_name": "broken", "litellm_params": {"model": "no-such-provider-model"}},
]
lookups: list[tuple[str, object]] = []
def resolver(provider: str, litellm_params) -> str | None:
lookups.append((provider, litellm_params.get("model")))
return "org-other" if litellm_params.get("chatgpt_auth_file") == "/logins/other.json" else _ACCOUNT
deployments = subscription_deployments_from_model_list(model_list, resolver)
assert deployments == (
*_TWO_DEPLOYMENTS_ONE_ACCOUNT,
SubscriptionDeployment(model_name="gpt-5.6-luna", custom_llm_provider="chatgpt", account_id="org-other"),
)
assert lookups == [
("chatgpt", "chatgpt/gpt-5.6-terra"),
("chatgpt", "chatgpt/gpt-5.6-sol"),
("chatgpt", "chatgpt/gpt-5.6-luna"),
]
@pytest.mark.parametrize(
"deployments",
[
(
*_TWO_DEPLOYMENTS_ONE_ACCOUNT,
SubscriptionDeployment(model_name="gpt-5.6-luna", custom_llm_provider="chatgpt", account_id="org-other"),
)
],
)
def test_two_logins_each_count_their_own_fee_once(client):
test_client, _ = client
other = {**_TEST_FEE, "account_id": "org-other", "monthly_fee": 40.0}
assert test_client.post("/subscription_accounts/new", json=_TEST_FEE).status_code == 200
assert test_client.post("/subscription_accounts/new", json=other).status_code == 200
body = _usage(test_client, "2026-10-01", "2026-10-07")
assert [(a["account_id"], a["deployments"], a["fixed_cost"]) for a in body["accounts"]] == [
("org-other", ["gpt-5.6-luna"], 40.0),
(_ACCOUNT, ["gpt-5.6-sol", "gpt-5.6-terra"], 25.0),
]

View file

@ -0,0 +1,73 @@
from datetime import date
from litellm.proxy.spend_tracking.subscription_billing_periods import (
BillingPeriodRange,
billing_periods_starting_within,
)
def test_one_period_per_month_start_inside_the_filter():
periods = billing_periods_starting_within(date(2026, 8, 5), date(2026, 9, 1), date(2026, 10, 31))
assert periods == (
BillingPeriodRange(start=date(2026, 9, 5), end=date(2026, 10, 4)),
BillingPeriodRange(start=date(2026, 10, 5), end=date(2026, 11, 4)),
)
def test_filter_boundaries_are_inclusive():
anchor = date(2026, 10, 1)
assert billing_periods_starting_within(anchor, date(2026, 10, 1), date(2026, 10, 7)) == (
BillingPeriodRange(start=date(2026, 10, 1), end=date(2026, 10, 31)),
)
assert billing_periods_starting_within(anchor, date(2026, 9, 25), date(2026, 10, 1)) == (
BillingPeriodRange(start=date(2026, 10, 1), end=date(2026, 10, 31)),
)
def test_filter_between_two_period_starts_attributes_nothing():
assert billing_periods_starting_within(date(2026, 10, 15), date(2026, 10, 1), date(2026, 10, 7)) == ()
def test_no_period_before_the_anchor():
assert billing_periods_starting_within(date(2026, 10, 1), date(2026, 8, 1), date(2026, 9, 30)) == ()
assert billing_periods_starting_within(date(2026, 10, 1), date(2026, 8, 1), date(2026, 10, 1)) == (
BillingPeriodRange(start=date(2026, 10, 1), end=date(2026, 10, 31)),
)
def test_anchor_day_clamps_to_short_months_without_drifting():
periods = billing_periods_starting_within(date(2026, 1, 31), date(2026, 2, 1), date(2026, 5, 31))
assert [period.start for period in periods] == [
date(2026, 2, 28),
date(2026, 3, 31),
date(2026, 4, 30),
date(2026, 5, 31),
]
assert periods[0].end == date(2026, 3, 30)
assert periods[-1].end == date(2026, 6, 29)
def test_period_ends_the_day_before_the_next_start_across_a_year_boundary():
periods = billing_periods_starting_within(date(2025, 12, 20), date(2025, 12, 1), date(2026, 1, 31))
assert periods == (
BillingPeriodRange(start=date(2025, 12, 20), end=date(2026, 1, 19)),
BillingPeriodRange(start=date(2026, 1, 20), end=date(2026, 2, 19)),
)
def test_inverted_filter_is_empty():
assert billing_periods_starting_within(date(2026, 1, 1), date(2026, 3, 1), date(2026, 2, 1)) == ()
def test_the_calendar_s_last_month_ends_on_its_last_day_instead_of_failing():
assert billing_periods_starting_within(date(9999, 11, 15), date(9999, 11, 1), date(9999, 12, 31)) == (
BillingPeriodRange(start=date(9999, 11, 15), end=date(9999, 12, 14)),
BillingPeriodRange(start=date(9999, 12, 15), end=date(9999, 12, 31)),
)
assert billing_periods_starting_within(date(9999, 12, 1), date(9999, 12, 1), date(9999, 12, 31)) == (
BillingPeriodRange(start=date(9999, 12, 1), end=date(9999, 12, 31)),
)

View file

@ -30,6 +30,11 @@ from litellm.repositories.object_permission_repository import (
)
from litellm.repositories.organization_repository import OrganizationRepository
from litellm.repositories.project_repository import ProjectRepository
from litellm.repositories.subscription_account_repository import (
SetLabel,
SubscriptionAccountFeeChanges,
SubscriptionAccountRepository,
)
from litellm.repositories.team_repository import TeamRepository
from litellm.repositories.user_repository import UserRepository
from litellm.repositories.verification_token_repository import (
@ -140,6 +145,7 @@ class MockPrismaClient:
self.db.litellm_projecttable = MockTable(pk_field="project_id")
self.db.litellm_objectpermissiontable = MockTable(pk_field="object_permission_id")
self.db.litellm_credentialstable = MockTable()
self.db.litellm_subscriptionaccounttable = MockTable(pk_field="subscription_account_id")
class TestBaseRepository:
@ -2461,3 +2467,40 @@ class TestAutoRouterSessionRepository:
assert AutoRouterSessionRepository(client).table is client.db.litellm_autoroutersession
with pytest.raises(RuntimeError, match="No DB Connected"):
_ = AutoRouterSessionRepository(None).table
class TestSubscriptionAccountRepository:
@pytest.mark.asyncio
async def test_update_fee_writes_only_the_named_columns(self):
client = MockPrismaClient()
stored_at = datetime(2026, 10, 1)
await client.db.litellm_subscriptionaccounttable.create(
data={
"subscription_account_id": "sub-1",
"custom_llm_provider": "chatgpt",
"account_id": "acct_123",
"label": "Team plan (test value)",
"monthly_fee": 25.0,
"currency": "USD",
"billing_period_start": "2026-10-01",
"created_at": stored_at,
"created_by": "admin-a",
"updated_at": stored_at,
"updated_by": "admin-a",
}
)
repo = SubscriptionAccountRepository(client)
fee_only = await repo.update_fee("sub-1", SubscriptionAccountFeeChanges(monthly_fee=30.0), "admin-b")
label_cleared = await repo.update_fee("sub-1", SubscriptionAccountFeeChanges(label=SetLabel(None)), "admin-c")
missing = await repo.update_fee("sub-2", SubscriptionAccountFeeChanges(monthly_fee=1.0), "admin-b")
assert fee_only is not None and label_cleared is not None
assert (fee_only.monthly_fee, fee_only.currency, fee_only.label, fee_only.updated_by) == (
30.0,
"USD",
"Team plan (test value)",
"admin-b",
)
assert (label_cleared.monthly_fee, label_cleared.label, label_cleared.updated_by) == (30.0, None, "admin-c")
assert missing is None

View file

@ -258,6 +258,34 @@ describe("SpendByProvider", () => {
expect(screen.getByTestId("provider-spend-total")).toHaveTextContent("$200.50");
});
it("always shows a subscription-covered provider and marks it included in the subscription", () => {
const providerSpendWithSubscription = [
{
provider: "chatgpt",
spend: 0,
requests: 7,
successful_requests: 7,
failed_requests: 0,
tokens: 11608,
subscription_covered: true,
},
{
provider: "google",
spend: 0,
requests: 0,
successful_requests: 0,
failed_requests: 0,
tokens: 0,
},
];
render(<SpendByProvider loading={false} isDateChanging={false} providerSpend={providerSpendWithSubscription} />);
expect(screen.getAllByText("chatgpt").length).toBeGreaterThan(0);
expect(screen.getByText("Included in subscription")).toBeInTheDocument();
expect(screen.getByText("11,608")).toBeInTheDocument();
expect(screen.queryByText("google")).not.toBeInTheDocument();
expect(screen.getByText("Included in subscription").closest("td")).not.toHaveTextContent("$");
});
it("should include all providers with spend greater than zero by default", () => {
const providerSpendWithMixed = [
{

View file

@ -4,6 +4,7 @@ import { MoneyCell } from "@/components/shared/table_cells";
import { formatNumberWithCommas } from "@/utils/dataUtils";
import { Info, Server } from "lucide-react";
import type { ColumnDef } from "@tanstack/react-table";
import { Badge } from "@/components/ui/badge";
import { Switch } from "@/components/ui/switch";
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
import React, { useId, useState } from "react";
@ -11,13 +12,14 @@ import { ProviderLogo } from "@/components/molecules/models/ProviderLogo";
import { ChartLoader } from "@/components/shared/chart_loader";
import { Panel } from "../overview/Primitives";
type ProviderSpendData = {
export type ProviderSpendData = {
provider: string;
spend: number;
requests: number;
successful_requests: number;
failed_requests: number;
tokens: number;
subscription_covered?: boolean;
};
interface SpendByProviderProps {
@ -48,7 +50,15 @@ const columns: ColumnDef<ProviderSpendData>[] = [
header: "Spend",
accessorKey: "spend",
meta: { numeric: true, ...QUIET_HEADER },
cell: ({ row }) => <MoneyCell value={row.original.spend} decimals={2} />,
cell: ({ row }) =>
row.original.subscription_covered ? (
<div className="flex items-center justify-end gap-2">
{row.original.spend > 0 && <MoneyCell value={row.original.spend} decimals={2} />}
<Badge variant="secondary">Included in subscription</Badge>
</div>
) : (
<MoneyCell value={row.original.spend} decimals={2} />
),
},
{
header: "Successful",
@ -164,6 +174,10 @@ const SpendByProvider: React.FC<SpendByProviderProps> = ({ loading, isDateChangi
return includeUnknown;
}
if (provider.subscription_covered) {
return true;
}
// If includeZeroSpend is true, include all providers (including those with 0 spend)
// Otherwise, only include providers with spend > 0
if (includeZeroSpend) {

View file

@ -0,0 +1,173 @@
import { fireEvent, render, screen } from "@testing-library/react";
import { describe, expect, it, vi } from "vitest";
import SubscriptionCostCard from "./SubscriptionCostCard";
import type { SubscriptionAccountUsage, SubscriptionFee } from "./types";
vi.mock("@/components/shared/chart_loader", () => ({
ChartLoader: () => <div data-testid="chart-loader">Loading chart data...</div>,
}));
vi.mock("@/components/molecules/models/ProviderLogo", () => ({
ProviderLogo: ({ provider }: { provider: string }) => <div data-testid={`provider-logo-${provider}`} />,
}));
const fee = (overrides: Partial<SubscriptionFee> = {}): SubscriptionFee => ({
subscription_account_id: "fee-1",
custom_llm_provider: "chatgpt",
account_id: "acct_123",
label: null,
monthly_fee: 25,
currency: "USD",
billing_period_start: "2026-10-01",
created_at: "2026-10-06T00:00:00Z",
updated_at: "2026-10-06T00:00:00Z",
created_by: "admin",
updated_by: "admin",
...overrides,
});
const account = (overrides: Partial<SubscriptionAccountUsage> = {}): SubscriptionAccountUsage => ({
custom_llm_provider: "chatgpt",
account_id: "acct_123",
deployments: ["gpt-5.6-terra", "gpt-5.6-sol"],
fee: null,
billing_periods: [],
fixed_cost: null,
...overrides,
});
const handlers = () => ({ onSetFee: vi.fn(), onEditFee: vi.fn(), onRemoveFee: vi.fn() });
const renderCard = (accounts: SubscriptionAccountUsage[], props: { canEdit?: boolean; meteredSpend?: number } = {}) => {
const actions = handlers();
const view = render(
<SubscriptionCostCard
loading={false}
failed={false}
isDateChanging={false}
usage={{ subscription_providers: ["chatgpt"], accounts }}
meteredSpend={props.meteredSpend ?? 0}
canEdit={props.canEdit ?? true}
{...actions}
/>,
);
return { ...view, ...actions };
};
describe("SubscriptionCostCard", () => {
it("renders nothing when there are no subscription accounts", () => {
const { container } = render(
<SubscriptionCostCard
loading={false}
failed={false}
isDateChanging={false}
usage={{ subscription_providers: [], accounts: [] }}
meteredSpend={0}
canEdit
{...handlers()}
/>,
);
expect(container).toBeEmptyDOMElement();
expect(screen.queryByText("Subscription fixed costs")).not.toBeInTheDocument();
});
it("calls out an untracked fixed cost and offers to set the fee only to an editor", () => {
const { onSetFee, unmount } = renderCard([account()]);
expect(screen.getByText("Fixed cost not tracked")).toBeInTheDocument();
expect(screen.getByText("gpt-5.6-terra, gpt-5.6-sol")).toBeInTheDocument();
expect(screen.getByText("None in range")).toBeInTheDocument();
expect(screen.getByTestId("fixed-cost-total")).toHaveTextContent("Fixed cost in range: none");
fireEvent.click(screen.getByRole("button", { name: "Set monthly fee" }));
expect(onSetFee).toHaveBeenCalledWith(account());
unmount();
renderCard([account()], { canEdit: false });
expect(screen.getByText("Fixed cost not tracked")).toBeInTheDocument();
expect(screen.queryByRole("button", { name: "Set monthly fee" })).not.toBeInTheDocument();
});
it("shows a configured fee once for two deployments sharing the account and the fixed cost in range", () => {
const covered = account({
fee: fee({ label: "Team workspace" }),
billing_periods: [{ start: "2026-10-01", end: "2026-10-31" }],
fixed_cost: 25,
});
const { onEditFee, onRemoveFee } = renderCard([covered], { meteredSpend: 0.0838 });
expect(screen.getAllByText("25.00 USD")).toHaveLength(2);
expect(screen.getByText("Team workspace")).toBeInTheDocument();
expect(screen.getByText("Oct 1 - Oct 31, 2026")).toBeInTheDocument();
expect(screen.getByTestId("fixed-cost-total")).toHaveTextContent("Fixed cost in range: 25.00 USD");
expect(screen.getByTestId("metered-spend")).toHaveTextContent("Metered spend: $0.08");
expect(screen.queryByText(/25\.08/)).not.toBeInTheDocument();
fireEvent.click(screen.getByRole("button", { name: "Edit" }));
expect(onEditFee).toHaveBeenCalledWith(covered);
fireEvent.click(screen.getByRole("button", { name: "Remove" }));
expect(onRemoveFee).toHaveBeenCalledWith(covered);
});
it("sums fixed costs per currency and keeps a second currency separate", () => {
const october = { start: "2026-10-01", end: "2026-10-31" };
const twoPeriods = {
fee: fee(),
billing_periods: [{ start: "2026-09-01", end: "2026-09-30" }, october],
fixed_cost: 50,
};
const secondUsd = { subscription_account_id: "fee-2", account_id: "acct_456", monthly_fee: 10 };
const noDeployments = {
account_id: "acct_456",
deployments: [],
fee: fee(secondUsd),
billing_periods: [october],
fixed_cost: 10,
};
const euro = { subscription_account_id: "fee-3", account_id: "acct_789", monthly_fee: 20, currency: "EUR" };
const inEuros = { account_id: "acct_789", fee: fee(euro), billing_periods: [october], fixed_cost: 20 };
renderCard([account(twoPeriods), account(noDeployments), account(inEuros)]);
const totals = screen.getAllByTestId("fixed-cost-total").map((node) => node.textContent);
expect(totals).toEqual(["Fixed cost in range: 60.00 USD", "Fixed cost in range: 20.00 EUR"]);
expect(screen.getByText("None")).toBeInTheDocument();
expect(screen.getByText("Sep 1 - Sep 30, 2026")).toBeInTheDocument();
});
it("explains an unresolved account and offers no action for it", () => {
renderCard([account({ account_id: null })]);
expect(screen.getByText("Account not signed in on the proxy")).toBeInTheDocument();
expect(screen.getByText("Fixed cost not tracked")).toBeInTheDocument();
expect(screen.queryByRole("button")).not.toBeInTheDocument();
});
it("shows the loader instead of the table while a range is loading", () => {
render(
<SubscriptionCostCard
loading
failed={false}
isDateChanging
usage={{ subscription_providers: ["chatgpt"], accounts: [account({ fee: fee(), fixed_cost: 25 })] }}
meteredSpend={0}
canEdit
{...handlers()}
/>,
);
expect(screen.getByTestId("chart-loader")).toBeInTheDocument();
expect(screen.queryByText("25.00 USD")).not.toBeInTheDocument();
});
it("says so instead of disappearing when the usage request fails", () => {
render(
<SubscriptionCostCard
loading={false}
failed
isDateChanging={false}
usage={null}
meteredSpend={0}
canEdit
{...handlers()}
/>,
);
expect(screen.getByText("Could not load subscription accounts for this range.")).toBeInTheDocument();
expect(screen.queryByTestId("chart-loader")).not.toBeInTheDocument();
});
});

View file

@ -0,0 +1,193 @@
import type { ColumnDef } from "@tanstack/react-table";
import { Info } from "lucide-react";
import React from "react";
import { ProviderLogo } from "@/components/molecules/models/ProviderLogo";
import { ChartLoader } from "@/components/shared/chart_loader";
import { DataTable } from "@/components/shared/DataTable";
import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
import { formatNumberWithCommas } from "@/utils/dataUtils";
import { ATTRIBUTION_RULE, fixedCostByCurrency, formatBillingPeriod, formatFee } from "./formatting";
import type { SubscriptionAccountUsage, SubscriptionUsageResponse } from "./types";
interface SubscriptionCostCardProps {
loading: boolean;
failed: boolean;
isDateChanging: boolean;
usage: SubscriptionUsageResponse | null;
meteredSpend: number;
canEdit: boolean;
onSetFee: (account: SubscriptionAccountUsage) => void;
onEditFee: (account: SubscriptionAccountUsage) => void;
onRemoveFee: (account: SubscriptionAccountUsage) => void;
}
type FeeActions = Pick<SubscriptionCostCardProps, "onSetFee" | "onEditFee" | "onRemoveFee">;
const accountRowId = (account: SubscriptionAccountUsage): string =>
`${account.custom_llm_provider}:${account.account_id ?? "unresolved"}`;
const AccountCell = ({ account }: { account: SubscriptionAccountUsage }) => {
if (account.account_id === null) {
return <span className="text-muted-foreground">Account not signed in on the proxy</span>;
}
return (
<div className="flex flex-col">
<span className="font-mono text-xs">{account.account_id}</span>
{account.fee?.label && <span className="text-xs text-muted-foreground">{account.fee.label}</span>}
</div>
);
};
const ActionsCell = ({
account,
onSetFee,
onEditFee,
onRemoveFee,
}: { account: SubscriptionAccountUsage } & FeeActions) => {
if (account.account_id === null) return null;
if (account.fee === null) {
return (
<Button variant="outline" size="xs" onClick={() => onSetFee(account)}>
Set monthly fee
</Button>
);
}
return (
<div className="flex justify-end gap-2">
<Button variant="outline" size="xs" onClick={() => onEditFee(account)}>
Edit
</Button>
<Button variant="outline" size="xs" onClick={() => onRemoveFee(account)}>
Remove
</Button>
</div>
);
};
const baseColumns: ColumnDef<SubscriptionAccountUsage>[] = [
{
header: "Provider",
accessorKey: "custom_llm_provider",
cell: ({ row }) => (
<div className="flex items-center space-x-2">
<ProviderLogo provider={row.original.custom_llm_provider} className="size-4" />
<span>{row.original.custom_llm_provider}</span>
</div>
),
},
{
header: "Account",
accessorKey: "account_id",
cell: ({ row }) => <AccountCell account={row.original} />,
},
{
header: "Deployments",
id: "deployments",
cell: ({ row }) => (row.original.deployments.length === 0 ? "None" : row.original.deployments.join(", ")),
},
{
header: "Monthly fee",
id: "monthly_fee",
meta: { numeric: true },
cell: ({ row }) =>
row.original.fee === null ? (
<Badge variant="outline">Fixed cost not tracked</Badge>
) : (
formatFee(row.original.fee.monthly_fee, row.original.fee.currency)
),
},
{
header: "Billing periods in range",
id: "billing_periods",
cell: ({ row }) =>
row.original.billing_periods.length === 0 ? (
<span className="text-muted-foreground">None in range</span>
) : (
<div className="flex flex-col">
{row.original.billing_periods.map((period) => (
<span key={period.start}>{formatBillingPeriod(period)}</span>
))}
</div>
),
},
{
header: "Fixed cost in range",
id: "fixed_cost",
meta: { numeric: true },
cell: ({ row }) =>
row.original.fee === null || row.original.fixed_cost === null
? "-"
: formatFee(row.original.fixed_cost, row.original.fee.currency),
},
];
const actionsColumn = (actions: FeeActions): ColumnDef<SubscriptionAccountUsage> => ({
header: "",
id: "actions",
meta: { numeric: true },
cell: ({ row }) => <ActionsCell account={row.original} {...actions} />,
});
const SubscriptionCostCard: React.FC<SubscriptionCostCardProps> = ({
loading,
failed,
isDateChanging,
usage,
meteredSpend,
canEdit,
onSetFee,
onEditFee,
onRemoveFee,
}) => {
if (!failed && (usage === null || usage.accounts.length === 0)) return null;
const columns = canEdit ? [...baseColumns, actionsColumn({ onSetFee, onEditFee, onRemoveFee })] : baseColumns;
const accounts = usage?.accounts ?? [];
const totals = fixedCostByCurrency(accounts);
return (
<Card className="col-span-2">
<CardHeader>
<CardTitle className="flex items-center gap-1">
Subscription fixed costs
<Tooltip>
<TooltipTrigger render={<Info className="size-4 text-muted-foreground hover:text-foreground" />} />
<TooltipContent>{ATTRIBUTION_RULE}</TooltipContent>
</Tooltip>
</CardTitle>
</CardHeader>
<CardContent>
{failed && <p className="text-sm text-destructive">Could not load subscription accounts for this range.</p>}
{!failed && loading && <ChartLoader isDateChanging={isDateChanging} />}
{!failed && !loading && (
<div className="flex flex-col gap-4">
<DataTable
columns={columns}
data={accounts}
getRowId={accountRowId}
noDataMessage="No subscription accounts"
size="compact"
/>
<div className="flex flex-wrap items-center gap-x-6 gap-y-1 text-sm">
{totals.length === 0 ? (
<span data-testid="fixed-cost-total">Fixed cost in range: none</span>
) : (
totals.map(({ currency, total }) => (
<span key={currency} data-testid="fixed-cost-total">
Fixed cost in range: {formatFee(total, currency)}
</span>
))
)}
<span data-testid="metered-spend">Metered spend: ${formatNumberWithCommas(meteredSpend, 2)}</span>
</div>
<p className="text-xs text-muted-foreground">{ATTRIBUTION_RULE}</p>
</div>
)}
</CardContent>
</Card>
);
};
export default SubscriptionCostCard;

View file

@ -0,0 +1,69 @@
import { fireEvent, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { renderWithProviders, testQueryClient } from "@/../tests/test-utils";
import { subscriptionAccountCreateCall, subscriptionUsageCall } from "@/components/networking";
import SubscriptionCosts from "./SubscriptionCosts";
import type { SubscriptionUsageResponse } from "./types";
vi.mock("@/components/networking", () => ({
formatDate: (date: Date) => date.toISOString().slice(0, 10),
subscriptionUsageCall: vi.fn(),
subscriptionAccountCreateCall: vi.fn().mockResolvedValue({}),
subscriptionAccountUpdateCall: vi.fn().mockResolvedValue({}),
subscriptionAccountDeleteCall: vi.fn().mockResolvedValue({}),
}));
vi.mock("@/lib/toast", () => ({ toast: { success: vi.fn(), fromError: vi.fn() } }));
const untracked: SubscriptionUsageResponse = {
start_date: "2026-10-01",
end_date: "2026-10-07",
subscription_providers: ["chatgpt"],
accounts: [
{
custom_llm_provider: "chatgpt",
account_id: "acct_123",
deployments: ["gpt-5.6-sol", "gpt-5.6-terra"],
fee: null,
billing_periods: [],
fixed_cost: null,
},
],
};
const fill = (label: string, value: string) => fireEvent.change(screen.getByLabelText(label), { target: { value } });
describe("SubscriptionCosts", () => {
beforeEach(() => {
testQueryClient.clear();
vi.clearAllMocks();
vi.mocked(subscriptionUsageCall).mockResolvedValue(untracked);
});
it("saves a fee set from the card on that card's account and reloads the card", async () => {
const user = userEvent.setup();
renderWithProviders(
<SubscriptionCosts
accessToken="sk-admin"
startTime={new Date("2026-10-01T00:00:00Z")}
endTime={new Date("2026-10-07T00:00:00Z")}
enabled
meteredSpend={0}
canEdit
/>,
);
await user.click(await screen.findByRole("button", { name: "Set monthly fee" }));
expect(screen.getByText("chatgpt account acct_123")).toBeInTheDocument();
fill("Monthly fee", "25");
fill("Currency", "USD");
fill("Billing period start", "2026-10-01");
await user.click(screen.getByRole("button", { name: "Save" }));
await waitFor(() => expect(subscriptionUsageCall).toHaveBeenCalledTimes(2));
expect(subscriptionAccountCreateCall).toHaveBeenCalledWith(
"sk-admin",
expect.objectContaining({ custom_llm_provider: "chatgpt", account_id: "acct_123", monthly_fee: 25 }),
);
});
});

View file

@ -0,0 +1,38 @@
import React from "react";
import { useSubscriptionUsage, type SubscriptionUsageOptions } from "../../hooks/useSubscriptionUsage";
import SubscriptionCostCard from "./SubscriptionCostCard";
import SubscriptionFeeModal from "./SubscriptionFeeModal";
import { useSubscriptionFeeActions } from "./useSubscriptionFeeActions";
interface SubscriptionCostsProps extends SubscriptionUsageOptions {
meteredSpend: number;
canEdit: boolean;
}
const SubscriptionCosts: React.FC<SubscriptionCostsProps> = ({ meteredSpend, canEdit, ...usageOptions }) => {
const usage = useSubscriptionUsage(usageOptions);
const feeActions = useSubscriptionFeeActions({ accessToken: usageOptions.accessToken, refetch: usage.refetch });
return (
<>
<SubscriptionCostCard
loading={usage.loading}
failed={usage.failed}
isDateChanging={false}
usage={usage.data}
meteredSpend={meteredSpend}
canEdit={canEdit}
onSetFee={feeActions.openFeeModal}
onEditFee={feeActions.openFeeModal}
onRemoveFee={feeActions.removeFee}
/>
<SubscriptionFeeModal
visible={feeActions.feeModalAccount !== null}
account={feeActions.feeModalAccount}
onCancel={feeActions.closeFeeModal}
onSubmit={feeActions.submitFee}
/>
</>
);
};
export default SubscriptionCosts;

View file

@ -0,0 +1,83 @@
import { fireEvent, render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { describe, expect, it, vi } from "vitest";
import SubscriptionFeeModal from "./SubscriptionFeeModal";
import type { SubscriptionAccountUsage } from "./types";
const account: SubscriptionAccountUsage = {
custom_llm_provider: "chatgpt",
account_id: "acct_123",
deployments: ["gpt-5.6-terra"],
fee: null,
billing_periods: [],
fixed_cost: null,
};
const fill = (label: string, value: string) => fireEvent.change(screen.getByLabelText(label), { target: { value } });
describe("SubscriptionFeeModal", () => {
it("submits normalized values for a new fee", async () => {
const onSubmit = vi.fn().mockResolvedValue(undefined);
render(<SubscriptionFeeModal visible account={account} onCancel={vi.fn()} onSubmit={onSubmit} />);
expect(screen.getByText("Set monthly fee")).toBeInTheDocument();
expect(screen.getByText("chatgpt account acct_123")).toBeInTheDocument();
fill("Monthly fee", "25");
fill("Currency", "usd");
fill("Billing period start", "2026-10-01");
fill("Label (optional)", "Team workspace");
await userEvent.setup().click(screen.getByRole("button", { name: "Save" }));
await waitFor(() => expect(onSubmit).toHaveBeenCalledTimes(1));
const normalized = {
monthly_fee: 25,
currency: "USD",
billing_period_start: "2026-10-01",
label: "Team workspace",
};
expect(onSubmit).toHaveBeenCalledWith(normalized);
});
it("rejects a zero fee and a two-letter currency", async () => {
const onSubmit = vi.fn().mockResolvedValue(undefined);
const user = userEvent.setup();
render(<SubscriptionFeeModal visible account={account} onCancel={vi.fn()} onSubmit={onSubmit} />);
fill("Monthly fee", "0");
fill("Billing period start", "2026-10-01");
await user.click(screen.getByRole("button", { name: "Save" }));
expect(await screen.findByText("Monthly fee must be greater than 0")).toBeInTheDocument();
fill("Monthly fee", "25");
fill("Currency", "US");
await user.click(screen.getByRole("button", { name: "Save" }));
expect(await screen.findByText("Currency must be a three-letter code")).toBeInTheDocument();
expect(onSubmit).not.toHaveBeenCalled();
});
it("prefills the existing fee when editing", () => {
const existing: SubscriptionAccountUsage = {
...account,
fee: {
subscription_account_id: "fee-1",
custom_llm_provider: "chatgpt",
account_id: "acct_123",
label: "Team workspace",
monthly_fee: 25,
currency: "EUR",
billing_period_start: "2026-09-15",
created_at: "2026-10-06T00:00:00Z",
updated_at: "2026-10-06T00:00:00Z",
created_by: "admin",
updated_by: "admin",
},
};
render(<SubscriptionFeeModal visible account={existing} onCancel={vi.fn()} onSubmit={vi.fn()} />);
expect(screen.getByText("Edit monthly fee")).toBeInTheDocument();
expect(screen.getByLabelText("Monthly fee")).toHaveValue(25);
expect(screen.getByLabelText("Currency")).toHaveValue("EUR");
expect(screen.getByLabelText("Billing period start")).toHaveValue("2026-09-15");
expect(screen.getByLabelText("Label (optional)")).toHaveValue("Team workspace");
});
});

View file

@ -0,0 +1,114 @@
"use client";
import React, { useEffect } from "react";
import { z } from "zod";
import { formatDate } from "@/components/networking";
import { FormField } from "@/components/shared/form/FormField";
import { Button } from "@/components/ui/button";
import {
Dialog,
DialogContent,
DialogDescription,
DialogFooter,
DialogHeader,
DialogTitle,
} from "@/components/ui/dialog";
import { FieldGroup } from "@/components/ui/field";
import { Input } from "@/components/ui/input";
import { useZodForm } from "@/lib/forms/useZodForm";
import type { SubscriptionAccountUsage, SubscriptionFeeFormValues } from "./types";
const feeShape = {
monthly_fee: z
.string()
.min(1, "Enter a monthly fee")
.refine((value) => Number(value) > 0, "Monthly fee must be greater than 0"),
currency: z
.string()
.trim()
.toUpperCase()
.regex(/^[A-Z]{3}$/, "Currency must be a three-letter code"),
billing_period_start: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Pick a billing period start date"),
label: z.string().trim(),
};
const feeSchema = z.object(feeShape);
type FeeFormInput = z.input<typeof feeSchema>;
const formInputFor = (account: SubscriptionAccountUsage | null): FeeFormInput => ({
monthly_fee: account?.fee ? String(account.fee.monthly_fee) : "",
currency: account?.fee?.currency ?? "USD",
billing_period_start: account?.fee?.billing_period_start ?? formatDate(new Date()),
label: account?.fee?.label ?? "",
});
interface SubscriptionFeeModalProps {
visible: boolean;
account: SubscriptionAccountUsage | null;
onCancel: () => void;
onSubmit: (values: SubscriptionFeeFormValues) => Promise<void>;
}
const SubscriptionFeeModal: React.FC<SubscriptionFeeModalProps> = ({ visible, account, onCancel, onSubmit }) => {
const form = useZodForm(feeSchema, { defaultValues: formInputFor(account) });
const { reset } = form;
useEffect(() => {
if (visible) reset(formInputFor(account));
}, [visible, account, reset]);
const handleFinish = async (values: z.output<typeof feeSchema>) => {
const submitted: SubscriptionFeeFormValues = {
monthly_fee: Number(values.monthly_fee),
currency: values.currency,
billing_period_start: values.billing_period_start,
label: values.label === "" ? null : values.label,
};
await onSubmit(submitted);
};
const handleCancel = () => {
reset(formInputFor(null));
onCancel();
};
return (
<Dialog open={visible} onOpenChange={(open) => !open && handleCancel()}>
<DialogContent className="sm:max-w-[480px]">
<DialogHeader>
<DialogTitle>{account?.fee ? "Edit monthly fee" : "Set monthly fee"}</DialogTitle>
<DialogDescription>
{account ? `${account.custom_llm_provider} account ${account.account_id ?? ""}` : ""}
</DialogDescription>
</DialogHeader>
<form onSubmit={form.handleSubmit(handleFinish)} noValidate>
<FieldGroup>
<FormField control={form.control} name="monthly_fee" label="Monthly fee">
{({ ref, ...field }) => <Input {...field} ref={ref} type="number" step={0.01} min={0.01} />}
</FormField>
<FormField control={form.control} name="currency" label="Currency">
{({ ref, ...field }) => <Input {...field} ref={ref} maxLength={3} />}
</FormField>
<FormField control={form.control} name="billing_period_start" label="Billing period start">
{({ ref, ...field }) => <Input {...field} ref={ref} type="date" />}
</FormField>
<FormField control={form.control} name="label" label="Label (optional)">
{({ ref, ...field }) => <Input {...field} ref={ref} />}
</FormField>
</FieldGroup>
<DialogFooter className="mt-4">
<Button type="button" variant="outline" onClick={handleCancel}>
Cancel
</Button>
<Button type="submit" disabled={form.formState.isSubmitting}>
Save
</Button>
</DialogFooter>
</form>
</DialogContent>
</Dialog>
);
};
export default SubscriptionFeeModal;

View file

@ -0,0 +1,34 @@
import type { BillingPeriod } from "./types";
export const ATTRIBUTION_RULE =
"A subscription fee is counted once for each monthly billing period whose start date falls inside the selected dates. Fixed costs sit beside metered spend and are never added to it, to key or team spend, or to budgets.";
export const formatFee = (amount: number, currency: string): string => `${amount.toFixed(2)} ${currency}`;
const parseLocalDay = (day: string): Date => {
const [year, month, date] = day.split("-").map(Number);
return new Date(year, month - 1, date);
};
export const formatBillingPeriod = ({ start, end }: BillingPeriod): string => {
const startDate = parseLocalDay(start);
const endDate = parseLocalDay(end);
const startLabel = startDate.toLocaleDateString("en-US", {
month: "short",
day: "numeric",
year: startDate.getFullYear() !== endDate.getFullYear() ? "numeric" : undefined,
});
const endLabel = endDate.toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
return `${startLabel} - ${endLabel}`;
};
export const fixedCostByCurrency = (
accounts: readonly { fee: { currency: string } | null; fixed_cost: number | null }[],
): readonly { currency: string; total: number }[] => {
const totals = new Map<string, number>();
accounts.forEach((account) => {
if (account.fee === null || account.fixed_cost === null) return;
totals.set(account.fee.currency, (totals.get(account.fee.currency) ?? 0) + account.fixed_cost);
});
return Array.from(totals, ([currency, total]) => ({ currency, total }));
};

View file

@ -0,0 +1,74 @@
import type { DailyData } from "@/components/UsagePage/types";
export interface SubscriptionFee {
subscription_account_id: string;
custom_llm_provider: string;
account_id: string;
label: string | null;
monthly_fee: number;
currency: string;
billing_period_start: string;
created_at: string;
updated_at: string;
created_by: string;
updated_by: string;
}
export interface BillingPeriod {
start: string;
end: string;
}
export interface SubscriptionAccountUsage {
custom_llm_provider: string;
account_id: string | null;
deployments: string[];
fee: SubscriptionFee | null;
billing_periods: BillingPeriod[];
fixed_cost: number | null;
}
export interface SubscriptionUsageResponse {
subscription_providers: string[];
accounts: SubscriptionAccountUsage[];
}
export interface SubscriptionAccountCreateRequest {
custom_llm_provider: string;
account_id: string;
monthly_fee: number;
currency: string;
billing_period_start: string;
label: string | null;
}
export interface SubscriptionAccountUpdateRequest {
subscription_account_id: string;
monthly_fee?: number;
currency?: string;
billing_period_start?: string;
label?: string | null;
}
export interface SubscriptionAccountDeleteRequest {
subscription_account_id: string;
}
export interface SubscriptionFeeFormValues {
monthly_fee: number;
currency: string;
billing_period_start: string;
label: string | null;
}
export const isSubscriptionCovered = (metadata: object | undefined): boolean =>
metadata !== undefined && "subscription_covered" in metadata && metadata.subscription_covered === true;
export const subscriptionCoveredProviders = (results: readonly DailyData[]): ReadonlySet<string> =>
new Set(
results.flatMap((day) =>
Object.entries(day.breakdown.providers ?? {})
.filter(([, entry]) => isSubscriptionCovered(entry.metadata))
.map(([provider]) => provider),
),
);

View file

@ -0,0 +1,79 @@
import { act, renderHook } from "@testing-library/react";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { subscriptionAccountCreateCall, subscriptionAccountUpdateCall } from "@/components/networking";
import type { SubscriptionAccountUsage, SubscriptionFeeFormValues } from "./types";
import { useSubscriptionFeeActions } from "./useSubscriptionFeeActions";
vi.mock("@/components/networking", () => ({
subscriptionAccountCreateCall: vi.fn().mockResolvedValue({}),
subscriptionAccountUpdateCall: vi.fn().mockResolvedValue({}),
subscriptionAccountDeleteCall: vi.fn(),
}));
vi.mock("@/lib/toast", () => ({ toast: { success: vi.fn(), fromError: vi.fn() } }));
const stored: SubscriptionFeeFormValues = {
monthly_fee: 25,
currency: "USD",
billing_period_start: "2026-10-01",
label: "Team plan (test value)",
};
const tracked: SubscriptionAccountUsage = {
custom_llm_provider: "chatgpt",
account_id: "acct_123",
deployments: ["gpt-5.6-terra"],
fee: {
subscription_account_id: "sub-1",
custom_llm_provider: "chatgpt",
account_id: "acct_123",
...stored,
created_at: "2026-10-01T00:00:00Z",
updated_at: "2026-10-01T00:00:00Z",
created_by: "admin",
updated_by: "admin",
},
billing_periods: [{ start: "2026-10-01", end: "2026-10-31" }],
fixed_cost: 25,
};
const submit = async (account: SubscriptionAccountUsage, values: SubscriptionFeeFormValues) => {
const refetch = vi.fn().mockResolvedValue(undefined);
const { result } = renderHook(() => useSubscriptionFeeActions({ accessToken: "sk-admin", refetch }));
act(() => result.current.openFeeModal(account));
await act(() => result.current.submitFee(values));
return { refetch, result };
};
describe("useSubscriptionFeeActions", () => {
beforeEach(() => vi.clearAllMocks());
it("sends only the fields the admin changed when editing a fee", async () => {
const { refetch, result } = await submit(tracked, { ...stored, monthly_fee: 30 });
expect(subscriptionAccountUpdateCall).toHaveBeenCalledWith("sk-admin", {
subscription_account_id: "sub-1",
monthly_fee: 30,
});
expect(refetch).toHaveBeenCalledTimes(1);
expect(result.current.feeModalAccount).toBeNull();
});
it("clears a label with an explicit null and nothing else", async () => {
await submit(tracked, { ...stored, label: null });
expect(subscriptionAccountUpdateCall).toHaveBeenCalledWith("sk-admin", {
subscription_account_id: "sub-1",
label: null,
});
});
it("creates a fee with every field for an untracked account", async () => {
const untracked: SubscriptionAccountUsage = { ...tracked, fee: null, billing_periods: [], fixed_cost: null };
const createRequest = { custom_llm_provider: "chatgpt", account_id: "acct_123", ...stored };
await submit(untracked, stored);
expect(subscriptionAccountCreateCall).toHaveBeenCalledWith("sk-admin", createRequest);
expect(subscriptionAccountUpdateCall).not.toHaveBeenCalled();
});
});

View file

@ -0,0 +1,90 @@
import { useCallback, useState } from "react";
import {
subscriptionAccountCreateCall,
subscriptionAccountDeleteCall,
subscriptionAccountUpdateCall,
} from "@/components/networking";
import { toast } from "@/lib/toast";
import type {
SubscriptionAccountUpdateRequest,
SubscriptionAccountUsage,
SubscriptionFee,
SubscriptionFeeFormValues,
} from "./types";
interface Options {
accessToken: string | null;
refetch: () => Promise<unknown>;
}
interface Result {
feeModalAccount: SubscriptionAccountUsage | null;
openFeeModal: (account: SubscriptionAccountUsage) => void;
closeFeeModal: () => void;
submitFee: (values: SubscriptionFeeFormValues) => Promise<void>;
removeFee: (account: SubscriptionAccountUsage) => Promise<void>;
}
const changedFields = (fee: SubscriptionFee, values: SubscriptionFeeFormValues): SubscriptionAccountUpdateRequest => ({
subscription_account_id: fee.subscription_account_id,
...(values.monthly_fee !== fee.monthly_fee && { monthly_fee: values.monthly_fee }),
...(values.currency !== fee.currency && { currency: values.currency }),
...(values.billing_period_start !== fee.billing_period_start && {
billing_period_start: values.billing_period_start,
}),
...(values.label !== fee.label && { label: values.label }),
});
const saveFee = (
accessToken: string,
account: SubscriptionAccountUsage,
values: SubscriptionFeeFormValues,
): Promise<unknown> | null => {
if (account.fee) {
return subscriptionAccountUpdateCall(accessToken, changedFields(account.fee, values));
}
if (account.account_id === null) return null;
return subscriptionAccountCreateCall(accessToken, {
custom_llm_provider: account.custom_llm_provider,
account_id: account.account_id,
...values,
});
};
export function useSubscriptionFeeActions({ accessToken, refetch }: Options): Result {
const [feeModalAccount, setFeeModalAccount] = useState<SubscriptionAccountUsage | null>(null);
const closeFeeModal = useCallback(() => setFeeModalAccount(null), []);
const submitFee = useCallback(
async (values: SubscriptionFeeFormValues) => {
if (!accessToken || feeModalAccount === null) return;
const request = saveFee(accessToken, feeModalAccount, values);
if (request === null) return;
try {
await request;
toast.success("Monthly fee saved");
setFeeModalAccount(null);
await refetch();
} catch (error) {
toast.fromError(error);
}
},
[accessToken, feeModalAccount, refetch],
);
const removeFee = useCallback(
async (account: SubscriptionAccountUsage) => {
if (!accessToken || account.fee === null) return;
try {
await subscriptionAccountDeleteCall(accessToken, account.fee.subscription_account_id);
toast.success("Monthly fee removed");
await refetch();
} catch (error) {
toast.fromError(error);
}
},
[accessToken, refetch],
);
return { feeModalAccount, openFeeModal: setFeeModalAccount, closeFeeModal, submitFee, removeFee };
}

View file

@ -8,7 +8,7 @@ import type { ComponentProps } from "react";
import userEvent from "@testing-library/user-event";
import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
import type { UrlUpdateEvent } from "nuqs/adapters/testing";
import { chooseSelectOption, renderWithProviders } from "@/../tests/test-utils";
import { chooseSelectOption, renderWithProviders, testQueryClient } from "@/../tests/test-utils";
import { toast } from "@/lib/toast";
import { processActivityData } from "@/components/activity_metrics";
import type { Organization } from "@/components/networking";
@ -74,6 +74,11 @@ beforeAll(() => {
// Mock the networking module
vi.mock("@/components/networking", () => ({
formatDate: (date: Date) => date.toISOString().slice(0, 10),
subscriptionUsageCall: vi.fn(),
subscriptionAccountCreateCall: vi.fn(),
subscriptionAccountUpdateCall: vi.fn(),
subscriptionAccountDeleteCall: vi.fn(),
dailyActivityAggregatedCall: vi.fn(),
dailyActivityKeyPageCall: vi.fn(),
userDailyActivityUserPageCall: vi.fn(),
@ -142,6 +147,14 @@ vi.mock("./EntityUsage/SpendByProvider", () => ({
default: () => <div>Spend By Provider</div>,
}));
vi.mock("./SubscriptionCost/SubscriptionCostCard", () => ({
default: ({ usage }: { usage: unknown }) => (
<div data-testid="subscription-cost-card" data-usage={JSON.stringify(usage)}>
Subscription Cost
</div>
),
}));
vi.mock("./EndpointUsage/EndpointUsage", () => ({
default: () => <div>Endpoint Usage</div>,
}));
@ -278,6 +291,7 @@ describe("UsagePage", () => {
const mockTagListCall = vi.mocked(networking.tagListCall);
const mockGatewayDailyActivityCall = vi.mocked(networking.gatewayDailyActivityCall);
const mockRequestErrorActivityCall = vi.mocked(networking.requestErrorActivityCall);
const mockSubscriptionUsageCall = vi.mocked(networking.subscriptionUsageCall);
const mockUseAgents = vi.mocked(useAgents);
const mockUseAuthorized = vi.mocked(useAuthorized);
const mockUseCurrentUser = vi.mocked(useCurrentUser);
@ -496,7 +510,24 @@ describe("UsagePage", () => {
organizations: [],
};
const mockSubscriptionUsage = {
subscription_providers: ["chatgpt"],
accounts: [
{
custom_llm_provider: "chatgpt",
account_id: "acct_123",
deployments: ["gpt-5.6-terra", "gpt-5.6-sol"],
fee: null,
billing_periods: [],
fixed_cost: null,
},
],
};
beforeEach(() => {
testQueryClient.clear();
mockSubscriptionUsageCall.mockReset();
mockSubscriptionUsageCall.mockResolvedValue(mockSubscriptionUsage);
mockClientUsagePanel.mockClear();
vi.mocked(processActivityData).mockReset();
vi.mocked(processActivityData).mockImplementation((_data, key) => ({
@ -578,6 +609,44 @@ describe("UsagePage", () => {
} as any);
});
it("hands the subscription usage to the fixed cost card for an admin and never fetches it otherwise", async () => {
const { unmount } = renderWithProviders(<UsagePage {...defaultProps} />);
await waitFor(() => {
expect(mockSubscriptionUsageCall).toHaveBeenCalledWith("test-token", expect.any(Date), expect.any(Date));
});
await waitFor(() => {
expect(screen.getByTestId("subscription-cost-card")).toHaveAttribute(
"data-usage",
JSON.stringify(mockSubscriptionUsage),
);
});
unmount();
for (const session of [nonAdminSession, { ...nonAdminSession, userRole: "org_admin" }]) {
mockSubscriptionUsageCall.mockClear();
mockUserDailyActivityAggregatedCall.mockClear();
mockUseAuthorized.mockReturnValue(session);
const rendered = renderWithProviders(<UsagePage {...defaultProps} />);
await waitFor(() => {
expect(mockUserDailyActivityAggregatedCall).toHaveBeenCalled();
});
expect(mockSubscriptionUsageCall).not.toHaveBeenCalled();
expect(screen.getByTestId("subscription-cost-card")).toHaveAttribute("data-usage", "null");
rendered.unmount();
}
});
it("never sets an account-wide subscription fee beside one user's spend when an admin filters by user", async () => {
renderWithProviders(<UsagePage {...defaultProps} />, { searchParams: "?user=user-001" });
await waitFor(() => {
expect(mockUserDailyActivityAggregatedCall).toHaveBeenCalledWith(
expect.objectContaining({ entityIds: ["user-001"] }),
);
});
expect(mockSubscriptionUsageCall).not.toHaveBeenCalled();
expect(screen.getByTestId("subscription-cost-card")).toHaveAttribute("data-usage", "null");
});
it("should render and fetch usage data on mount", async () => {
renderWithProviders(<UsagePage {...defaultProps} />);

View file

@ -26,7 +26,7 @@ import { useOrganizations } from "@/app/(dashboard)/hooks/organizations/useOrgan
import { toast } from "@/lib/toast";
import { hasCapability } from "@/utils/capabilities";
import { copyToClipboard } from "@/utils/dataUtils";
import { hasProxyWideSpendView, internalUserRoles } from "@/utils/roles";
import { hasProxyWideSpendView, internalUserRoles, isProxyAdminRole } from "@/utils/roles";
import { ActivityMetrics, processActivityData } from "@/components/activity_metrics";
import CloudZeroExportModal from "@/components/cloudzero_export_modal";
import UserDropdown from "@/components/common_components/UserDropdown";
@ -92,7 +92,7 @@ import {
usageViewFromParams,
usageViewPatch,
} from "../usageUrlState";
import { overviewTotals, rollUpBreakdown } from "./overview/overviewData";
import { overviewTotals, providerSpendRows } from "./overview/overviewData";
import TopAgents from "./overview/TopAgents";
import { parseUsageClient, topAgents, type AgentRow } from "./overview/agentCatalog";
import ClientUsagePanel from "./ClientUsagePanel";
@ -100,6 +100,7 @@ import { resolveClientUsageScope } from "../hooks/clientUsageScope";
import { useUsagePanelContext } from "../hooks/useUsagePanelContext";
import ClientUsageSelect from "./ClientUsageSelect";
import SpendByProvider from "./EntityUsage/SpendByProvider";
import SubscriptionCosts from "./SubscriptionCost/SubscriptionCosts";
import { useTagSummary } from "@/app/(dashboard)/hooks/tags/useTagSummary";
import { Panel } from "./overview/Primitives";
import UsageOverview from "./overview/UsageOverview";
@ -374,10 +375,7 @@ const UsagePage: React.FC<UsagePageProps> = ({ teams, organizations, teamsLoadin
() => overviewTotals(userSpendData.metadata, gatewayActivity),
[userSpendData.metadata, gatewayActivity],
);
const providerSpend = useMemo(
() => rollUpBreakdown(userSpendData.results, "providers").map(({ key, ...row }) => ({ provider: key, ...row })),
[userSpendData.results],
);
const providerSpend = useMemo(() => providerSpendRows(userSpendData.results), [userSpendData.results]);
const {
data: tagSummary,
isLoading: tagSummaryLoading,
@ -546,6 +544,16 @@ const UsagePage: React.FC<UsagePageProps> = ({ teams, organizations, teamsLoadin
loading={loading}
requestCountsPending={requestCountsPending}
budget={currentUser?.max_budget ?? null}
subscriptionCosts={
<SubscriptionCosts
accessToken={accessToken}
startTime={startTime}
endTime={endTime}
enabled={isAdmin && effectiveUserId === null}
meteredSpend={totals.spend}
canEdit={isProxyAdminRole(userRole || "")}
/>
}
topKeys={
<TopKeyView
topKeys={topKeys}

View file

@ -20,6 +20,7 @@ interface UsageOverviewProps {
loading: boolean;
requestCountsPending: boolean;
budget: number | null;
subscriptionCosts: ReactNode;
topKeys: ReactNode;
topUsers: ReactNode;
gatewayByEndpoint: ReactNode;
@ -32,6 +33,7 @@ export default function UsageOverview({
totals,
loading,
requestCountsPending,
subscriptionCosts,
topKeys,
topUsers,
gatewayByEndpoint,
@ -49,6 +51,8 @@ export default function UsageOverview({
budget={budget}
/>
{subscriptionCosts}
<UsageBreakdownChart results={results} loading={loading} />
{topAgents}

View file

@ -7,6 +7,7 @@ import {
labelForDate,
modelColorMap,
OTHER_COLOR,
providerSpendRows,
rollUpBreakdown,
seriesBy,
} from "./overviewData";
@ -88,6 +89,34 @@ describe("bucketSeries", () => {
});
});
const providerDay = (date: string, providers: Record<string, Record<string, unknown>>): DailyData =>
({
...day(date, 0, {}),
breakdown: {
...day(date, 0, {}).breakdown,
providers: Object.fromEntries(
Object.entries(providers).map(([name, metadata]) => [
name,
{ metrics: metrics(0), metadata, api_key_breakdown: {} },
]),
),
},
}) as unknown as DailyData;
describe("providerSpendRows", () => {
it("marks a provider covered by a subscription on any day of the range and leaves metered ones unmarked", () => {
const rows = providerSpendRows([
providerDay("2026-10-01", { chatgpt: {}, openai: {} }),
providerDay("2026-10-02", { chatgpt: { subscription_covered: true }, openai: { subscription_covered: false } }),
]);
expect(Object.fromEntries(rows.map((row) => [row.provider, row.subscription_covered]))).toEqual({
chatgpt: true,
openai: false,
});
expect(rows.find((row) => row.provider === "chatgpt")).toEqual(expect.objectContaining({ requests: 2 }));
});
});
describe("rollUpBreakdown", () => {
it("sums a dimension across days without changing the input", () => {
const days = [day("2026-10-01", 3, { a: 3 }), day("2026-10-02", 2, { a: 2 })];

View file

@ -2,6 +2,7 @@ import type { DailyData, SpendMetrics } from "@/components/UsagePage/types";
import { stackedUsageColor } from "@/components/shared/charts";
import { EMPTY_DAILY_ACTIVITY_METADATA, type DailyActivityMetadata } from "@/components/UsagePage/dailyActivityApi";
import type { GatewayActivity } from "../gatewayActivity";
import { subscriptionCoveredProviders } from "../SubscriptionCost/types";
export type BreakdownDimension = "models" | "model_groups" | "providers";
@ -40,6 +41,15 @@ export const rollUpBreakdown = (results: readonly DailyData[], dimension: Breakd
return [...totals.values()].sort((a, b) => b.spend - a.spend);
};
export const providerSpendRows = (results: readonly DailyData[]) => {
const covered = subscriptionCoveredProviders(results);
return rollUpBreakdown(results, "providers").map(({ key, ...row }) => ({
provider: key,
...row,
subscription_covered: covered.has(key),
}));
};
export const modelColorMap = (results: readonly DailyData[]): ReadonlyMap<string, string> => {
const groups = rollUpBreakdown(results, "model_groups");
const models = rollUpBreakdown(results, "models");

View file

@ -0,0 +1,47 @@
import { keepPreviousData, queryOptions, skipToken, useQuery } from "@tanstack/react-query";
import { formatDate, subscriptionUsageCall } from "@/components/networking";
import type { SubscriptionUsageResponse } from "../components/SubscriptionCost/types";
export interface SubscriptionUsageOptions {
accessToken: string | null;
startTime: Date | null;
endTime: Date | null;
enabled: boolean;
}
interface Result {
data: SubscriptionUsageResponse | null;
loading: boolean;
failed: boolean;
refetch: () => Promise<unknown>;
}
interface UsageRequest {
accessToken: string;
startTime: Date;
endTime: Date;
}
const subscriptionUsageQuery = (request: UsageRequest | null) => {
const queryKey = [
"subscriptionUsage",
request ? formatDate(request.startTime) : null,
request ? formatDate(request.endTime) : null,
];
const queryFn = request
? () => subscriptionUsageCall(request.accessToken, request.startTime, request.endTime)
: skipToken;
return queryOptions({ queryKey, queryFn, placeholderData: keepPreviousData });
};
export function useSubscriptionUsage({ accessToken, startTime, endTime, enabled }: SubscriptionUsageOptions): Result {
const range = startTime && endTime ? { startTime, endTime } : null;
const request = enabled && accessToken && range ? { accessToken, ...range } : null;
const query = useQuery(subscriptionUsageQuery(request));
return {
data: request && query.data ? query.data : null,
loading: request !== null && (query.isPending || query.isPlaceholderData),
failed: query.isError,
refetch: query.refetch,
};
}

View file

@ -119,6 +119,13 @@ import { MCP_TOOLS_PREVIEW_FORBIDDEN_MESSAGE } from "./mcp_tools/constants";
import type { ComplexityRouterConfigPayload } from "./add_model/build_complexity_router_config";
import type { AutoRouterPresetsResponse } from "@/lib/autorouter_presets";
import type { VectorStoreIndex } from "@/app/(dashboard)/vector-stores/_components/IndexesTab";
import type {
SubscriptionAccountCreateRequest,
SubscriptionAccountDeleteRequest,
SubscriptionAccountUpdateRequest,
SubscriptionFee,
SubscriptionUsageResponse,
} from "@/app/(dashboard)/usage/_components/components/SubscriptionCost/types";
import type { RoutingDecision } from "./logs/detail/RoutingDecisionCard";
import type {
SpanDetail,
@ -1395,6 +1402,34 @@ export const dailyActivityAggregatedCall = (
query: dailyActivityQuery(entity, req, req.apiKeyLimit === undefined ? {} : { api_key_limit: req.apiKeyLimit }),
});
export const subscriptionUsageCall = (
accessToken: string,
startTime: Date,
endTime: Date,
): Promise<SubscriptionUsageResponse> =>
apiClient.get<SubscriptionUsageResponse>("/subscription_accounts/usage", {
accessToken,
query: { start_date: formatDate(startTime), end_date: formatDate(endTime) },
});
export const subscriptionAccountCreateCall = (
accessToken: string,
body: SubscriptionAccountCreateRequest,
): Promise<SubscriptionFee> => apiClient.post<SubscriptionFee>("/subscription_accounts/new", { accessToken, body });
export const subscriptionAccountUpdateCall = (
accessToken: string,
body: SubscriptionAccountUpdateRequest,
): Promise<SubscriptionFee> => apiClient.post<SubscriptionFee>("/subscription_accounts/update", { accessToken, body });
export const subscriptionAccountDeleteCall = (
accessToken: string,
subscriptionAccountId: string,
): Promise<SubscriptionFee> => {
const body: SubscriptionAccountDeleteRequest = { subscription_account_id: subscriptionAccountId };
return apiClient.post<SubscriptionFee>("/subscription_accounts/delete", { accessToken, body });
};
export const dailyActivityKeyPageCall = (
entity: DailyActivityEntity,
req: DailyActivityRequest,

View file

@ -16040,6 +16040,90 @@ export interface paths {
patch?: never;
trace?: never;
};
"/subscription_accounts/delete": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
get?: never;
put?: never;
/**
* Delete Subscription Account
* @description Stop tracking a subscription account's fee; its requests stay marked as subscription-covered.
*/
post: operations["delete_subscription_account_subscription_accounts_delete_post"];
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/subscription_accounts/new": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
get?: never;
put?: never;
/**
* New Subscription Account
* @description Record the monthly fee of one subscription-backed provider account.
*/
post: operations["new_subscription_account_subscription_accounts_new_post"];
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/subscription_accounts/update": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
get?: never;
put?: never;
/**
* Update Subscription Account
* @description Change the fee, currency, billing period start, or label of a subscription account.
* Only the fields named in the request are written, so two admins changing different
* fields at the same time both land.
*/
post: operations["update_subscription_account_subscription_accounts_update_post"];
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/subscription_accounts/usage": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
/**
* Get Subscription Usage
* @description Subscription-backed accounts behind the proxy's deployments, each with its configured
* monthly fee and the fixed cost attributed to the date range: the fee once per billing
* period whose start date falls inside the range, however many deployments share the account.
*/
get: operations["get_subscription_usage_subscription_accounts_usage_get"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/systemone": {
parameters: {
query?: never;
@ -27350,6 +27434,19 @@ export interface components {
/** Entities */
entities: components["schemas"]["BedrockChecksSensitiveInformationEntityItem"][];
};
/** BillingPeriod */
BillingPeriod: {
/**
* End
* Format: date
*/
end: string;
/**
* Start
* Format: date
*/
start: string;
};
/** BlockKeyRequest */
BlockKeyRequest: {
/** Key */
@ -31824,6 +31921,11 @@ export interface components {
*/
type: string;
};
/** DeleteSubscriptionAccountRequest */
DeleteSubscriptionAccountRequest: {
/** Subscription Account Id */
subscription_account_id: string;
};
/** DeleteTeamRequest */
DeleteTeamRequest: {
/** Team Ids */
@ -35913,6 +36015,37 @@ export interface components {
*/
user: string | null;
};
/** LiteLLM_SubscriptionAccountTable */
LiteLLM_SubscriptionAccountTable: {
/** Account Id */
account_id: string;
/** Billing Period Start */
billing_period_start: string;
/**
* Created At
* Format: date-time
*/
created_at: string;
/** Created By */
created_by: string;
/** Currency */
currency: string;
/** Custom Llm Provider */
custom_llm_provider: string;
/** Label */
label?: string | null;
/** Monthly Fee */
monthly_fee: number;
/** Subscription Account Id */
subscription_account_id: string;
/**
* Updated At
* Format: date-time
*/
updated_at: string;
/** Updated By */
updated_by: string;
};
/** LiteLLM_TeamMembership */
LiteLLM_TeamMembership: {
/** Budget Id */
@ -46121,6 +46254,55 @@ export interface components {
/** Window Start */
window_start: number;
};
/** SubscriptionAccountFeeRequest */
SubscriptionAccountFeeRequest: {
/** Account Id */
account_id: string;
/**
* Billing Period Start
* Format: date
*/
billing_period_start: string;
/** Currency */
currency: string;
/** Custom Llm Provider */
custom_llm_provider: string;
/** Label */
label?: string | null;
/** Monthly Fee */
monthly_fee: number;
};
/** SubscriptionAccountUsage */
SubscriptionAccountUsage: {
/** Account Id */
account_id: string | null;
/** Billing Periods */
billing_periods: components["schemas"]["BillingPeriod"][];
/** Custom Llm Provider */
custom_llm_provider: string;
/** Deployments */
deployments: string[];
fee: components["schemas"]["LiteLLM_SubscriptionAccountTable"] | null;
/** Fixed Cost */
fixed_cost: number | null;
};
/** SubscriptionUsageResponse */
SubscriptionUsageResponse: {
/** Accounts */
accounts: components["schemas"]["SubscriptionAccountUsage"][];
/**
* End Date
* Format: date
*/
end_date: string;
/**
* Start Date
* Format: date
*/
start_date: string;
/** Subscription Providers */
subscription_providers: string[];
};
/**
* SuccessfulKeyUpdate
* @description Successfully updated key with its updated information
@ -48789,6 +48971,19 @@ export interface components {
UpdateSearchToolRequest: {
search_tool: components["schemas"]["SearchTool"];
};
/** UpdateSubscriptionAccountFeeRequest */
UpdateSubscriptionAccountFeeRequest: {
/** Billing Period Start */
billing_period_start?: string | null;
/** Currency */
currency?: string | null;
/** Label */
label?: string | null;
/** Monthly Fee */
monthly_fee?: number | null;
/** Subscription Account Id */
subscription_account_id: string;
};
/**
* UpdateTeamMemberPermissionsRequest
* @description Request to update the team member permissions for a team
@ -72716,6 +72911,139 @@ export interface operations {
};
};
};
delete_subscription_account_subscription_accounts_delete_post: {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["DeleteSubscriptionAccountRequest"];
};
};
responses: {
/** @description Successful Response */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["LiteLLM_SubscriptionAccountTable"];
};
};
/** @description Validation Error */
422: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["HTTPValidationError"];
};
};
};
};
new_subscription_account_subscription_accounts_new_post: {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["SubscriptionAccountFeeRequest"];
};
};
responses: {
/** @description Successful Response */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["LiteLLM_SubscriptionAccountTable"];
};
};
/** @description Validation Error */
422: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["HTTPValidationError"];
};
};
};
};
update_subscription_account_subscription_accounts_update_post: {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["UpdateSubscriptionAccountFeeRequest"];
};
};
responses: {
/** @description Successful Response */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["LiteLLM_SubscriptionAccountTable"];
};
};
/** @description Validation Error */
422: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["HTTPValidationError"];
};
};
};
};
get_subscription_usage_subscription_accounts_usage_get: {
parameters: {
query: {
/** @description First day of the Usage page filter, YYYY-MM-DD */
start_date: string;
/** @description Last day of the Usage page filter, YYYY-MM-DD */
end_date: string;
};
header?: never;
path?: never;
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Successful Response */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["SubscriptionUsageResponse"];
};
};
/** @description Validation Error */
422: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["HTTPValidationError"];
};
};
};
};
systemone_systemone_post: {
parameters: {
query?: never;