Tenant billing lifecycle — plans, subscriptions, invoices, expiry

clients/admin/src/api/billing.ts

@@ -9,6 +9,10 @@ export type SubscriptionStatus = "Active" | "Suspended" | "Cancelled" | (string
 
 export type InvoiceLineItemKind = "BaseFee" | "Overage" | "Adjustment" | (string & {});
 
+export type PlanInterval = "Monthly" | "Yearly" | (string & {});
+
+export type InvoicePurpose = "Usage" | "Subscription" | (string & {});
+
 export type QuotaResource =
   | "ApiCalls"
   | "StorageBytes"
@@ -26,6 +30,8 @@ export type BillingPlanDto = {
   monthlyBasePrice: number;
   overageRates: Partial<Record<QuotaResource, number>>;
   isActive: boolean;
+  interval: PlanInterval;
+  annualPrice?: number | null;
 };
 
 export type CreatePlanInput = {
@@ -34,15 +40,26 @@ export type CreatePlanInput = {
   currency: string;
   monthlyBasePrice: number;
   overageRates?: Partial<Record<QuotaResource, number>> | null;
+  interval?: PlanInterval;
+  annualPrice?: number | null;
 };
 
 export type UpdatePlanInput = {
   planId: string;
   name: string;
   monthlyBasePrice: number;
   overageRates?: Partial<Record<QuotaResource, number>> | null;
+  interval?: PlanInterval;
+  annualPrice?: number | null;
 };
 
+/** Price charged for one billing term: annual price (or 12x monthly) for yearly plans, else monthly. */
+export function planTermPrice(plan: Pick<BillingPlanDto, "interval" | "monthlyBasePrice" | "annualPrice">): number {
+  return plan.interval === "Yearly"
+    ? plan.annualPrice ?? plan.monthlyBasePrice * 12
+    : plan.monthlyBasePrice;
+}
+
 export function getPlans(includeInactive = false): Promise<BillingPlanDto[]> {
   const query = new URLSearchParams({ includeInactive: includeInactive ? "true" : "false" });
   return apiFetch<BillingPlanDto[]>(`/api/v1/billing/plans?${query.toString()}`);
@@ -57,6 +74,8 @@ export function createPlan(input: CreatePlanInput): Promise<string> {
       currency: input.currency,
       monthlyBasePrice: input.monthlyBasePrice,
       overageRates: input.overageRates ?? null,
+      interval: input.interval ?? "Monthly",
+      annualPrice: input.annualPrice ?? null,
     }),
   });
 }
@@ -69,6 +88,8 @@ export function updatePlan(input: UpdatePlanInput): Promise<string> {
       name: input.name,
       monthlyBasePrice: input.monthlyBasePrice,
       overageRates: input.overageRates ?? null,
+      interval: input.interval ?? "Monthly",
+      annualPrice: input.annualPrice ?? null,
     }),
   });
 }
@@ -132,6 +153,9 @@ export type InvoiceDto = {
   voidedAtUtc?: string | null;
   notes?: string | null;
   lineItems: InvoiceLineItemDto[];
+  purpose: InvoicePurpose;
+  periodStartUtc?: string | null;
+  periodEndUtc?: string | null;
 };
 
 export type ListInvoicesParams = {

clients/admin/src/api/tenants.ts

@@ -3,13 +3,19 @@ import type { PagedResponse } from "@/lib/api-types";
 
 export type { PagedResponse } from "@/lib/api-types";
 
+export type TenantExpiryState = "Active" | "InGrace" | "Expired" | (string & {});
+
 export type TenantDto = {
   id: string;
   name: string;
   adminEmail: string;
   isActive: boolean;
   validUpto: string;
   issuer?: string;
+  /** Present on the status endpoint (TenantStatusDto); absent on the list projection. */
+  plan?: string | null;
+  expiryState?: TenantExpiryState;
+  graceEndsUtc?: string;
 };
 
 export type ListTenantsParams = {
@@ -25,6 +31,15 @@ export type CreateTenantInput = {
   adminPassword: string;
   issuer: string;
   connectionString?: string | null;
+  /** Plan key to subscribe the tenant to. Omitted → server falls back to the default/trial plan. */
+  planKey?: string | null;
+};
+
+export type RenewTenantResponse = {
+  tenantId: string;
+  validUpto: string;
+  planKey: string;
+  planChanged: boolean;
 };
 
 export type CreateTenantResponse = {
@@ -84,10 +99,19 @@ export async function createTenant(input: CreateTenantInput): Promise<CreateTena
       adminPassword: input.adminPassword,
       issuer: input.issuer,
       connectionString: input.connectionString ?? null,
+      planKey: input.planKey ?? null,
     }),
   });
 }
 
+/** Renew a tenant for one more plan term, optionally switching plans. */
+export async function renewTenant(id: string, planKey?: string | null): Promise<RenewTenantResponse> {
+  return apiFetch<RenewTenantResponse>(`/api/v1/tenants/${encodeURIComponent(id)}/renew`, {
+    method: "POST",
+    body: JSON.stringify({ tenantId: id, planKey: planKey ?? null }),
+  });
+}
+
 export async function changeTenantActivation(id: string, isActive: boolean): Promise<TenantLifecycleResult> {
   return apiFetch<TenantLifecycleResult>(`/api/v1/tenants/${encodeURIComponent(id)}/activation`, {
     method: "POST",