Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. πŸ”₯

fix: correct Autumn billing period timestamps, subscription lookup, and planCredits (#3364)

devin-ai-integration[bot]267e86cf1d6b
diff --git a/apps/api/src/services/autumn/__tests__/usage.test.ts b/apps/api/src/services/autumn/__tests__/usage.test.ts
index f22ec1220..54900d13c 100644
--- a/apps/api/src/services/autumn/__tests__/usage.test.ts
+++ b/apps/api/src/services/autumn/__tests__/usage.test.ts
@@ -1,9 +1,17 @@
-import { jest } from "@jest/globals";
+import { jest, beforeEach } from "@jest/globals";
const mockAggregate = jest.fn<(args: any) => Promise<any>>();
+const mockEntitiesGet = jest.fn<(args: any) => Promise<any>>();
+const mockCustomersGetOrCreate = jest.fn<(args: any) => Promise<any>>();
-let autumnClientRef: { events: { aggregate: typeof mockAggregate } } | null = {
+let autumnClientRef: {
+ events: { aggregate: typeof mockAggregate };
+ entities: { get: typeof mockEntitiesGet };
+ customers: { getOrCreate: typeof mockCustomersGetOrCreate };
+} | null = {
events: { aggregate: mockAggregate },
+ entities: { get: mockEntitiesGet },
+ customers: { getOrCreate: mockCustomersGetOrCreate },
};
let teamLookup = {
@@ -46,17 +54,668 @@ jest.mock("../../supabase", () => ({
}));
import {
+ getTeamBalance,
getTeamHistoricalUsage,
getTeamHistoricalUsageByApiKey,
} from "../usage";
beforeEach(() => {
jest.clearAllMocks();
- autumnClientRef = { events: { aggregate: mockAggregate } };
+ autumnClientRef = {
+ events: { aggregate: mockAggregate },
+ entities: { get: mockEntitiesGet },
+ customers: { getOrCreate: mockCustomersGetOrCreate },
+ };
teamLookup = { data: { org_id: "org-1" }, error: null };
apiKeysData = [];
});
+// ---------------------------------------------------------------------------
+// getTeamBalance β€” covers all four billing-period / planCredits bug fixes
+// ---------------------------------------------------------------------------
+
+describe("getTeamBalance", () => {
+ // Bug 1: Autumn returns currentPeriodStart/End as ms timestamps.
+ // The old code did `new Date(epoch * 1000)` which produced year ~58000.
+ // The fix passes them directly to `new Date()`.
+ it("Bug 1 β€” passes ms timestamps directly without * 1000", async () => {
+ const startMs = 1712444524000; // 2024-04-06T21:32:04.000Z
+ const endMs = 1715036524000; // 2024-05-06T21:32:04.000Z
+
+ mockEntitiesGet.mockResolvedValue({
+ balances: {
+ CREDITS: {
+ remaining: 461027,
+ granted: 500000,
+ usage: 38973,
+ unlimited: false,
+ breakdown: [{ planId: "growth", includedGrant: 500000 }],
+ },
+ },
+ subscriptions: [
+ {
+ status: "active",
+ currentPeriodStart: startMs,
+ currentPeriodEnd: endMs,
+ },
+ ],
+ });
+
+ const result = await getTeamBalance("team-1");
+
+ expect(result).not.toBeNull();
+ expect(result!.periodStart).toBe(new Date(startMs).toISOString());
+ expect(result!.periodEnd).toBe(new Date(endMs).toISOString());
+
+ // Confirm dates are in a sane range (not year 58000+)
+ const startYear = new Date(result!.periodStart!).getFullYear();
+ const endYear = new Date(result!.periodEnd!).getFullYear();
+ expect(startYear).toBeGreaterThanOrEqual(2020);
+ expect(startYear).toBeLessThan(2100);
+ expect(endYear).toBeGreaterThanOrEqual(2020);
+ expect(endYear).toBeLessThan(2100);
+ });
+
+ // If Autumn ever switches to seconds, this ensures the code produces a
+ // sane date from whatever epoch format it receives.
+ it("Bug 1 β€” would produce year ~58000 if timestamps were erroneously multiplied by 1000", async () => {
+ const startMs = 1712444524000;
+ const endMs = 1715036524000;
+
+ // Simulating what the OLD code would have done: new Date(startMs * 1000)
+ const brokenDate = new Date(startMs * 1000);
+ expect(brokenDate.getFullYear()).toBeGreaterThan(50000);
+
+ // The fix: new Date(startMs) directly
+ const fixedDate = new Date(startMs);
+ expect(fixedDate.getFullYear()).toBe(2024);
+ });
+
+ // Bug 2: Autumn uses "active"/"scheduled", not Stripe's "trialing"/"past_due".
+ // The old filter for "active" || "trialing" || "past_due" missed scheduled subs.
+ it("Bug 2 β€” finds subscription with 'active' status (Autumn's status model)", async () => {
+ mockEntitiesGet.mockResolvedValue({
+ balances: {
+ CREDITS: {
+ remaining: 100,
+ granted: 1000,
+ usage: 900,
+ unlimited: false,
+ breakdown: [{ planId: "standard", includedGrant: 1000 }],
+ },
+ },
+ subscriptions: [
+ {
+ status: "active",
+ currentPeriodStart: 1712444524000,
+ currentPeriodEnd: 1715036524000,
+ },
+ ],
+ });
+
+ const result = await getTeamBalance("team-1");
+ expect(result).not.toBeNull();
+ expect(result!.periodStart).not.toBeNull();
+ expect(result!.periodEnd).not.toBeNull();
+ });
+
+ it("Bug 2 β€” falls back to any subscription with period timestamps when none is 'active'", async () => {
+ mockEntitiesGet.mockResolvedValue({
+ balances: {
+ CREDITS: {
+ remaining: 50,
+ granted: 500,
+ usage: 450,
+ unlimited: false,
+ breakdown: [{ planId: "growth", includedGrant: 500 }],
+ },
+ },
+ subscriptions: [
+ {
+ status: "scheduled",
+ currentPeriodStart: 1712444524000,
+ currentPeriodEnd: 1715036524000,
+ },
+ ],
+ });
+
+ const result = await getTeamBalance("team-1");
+ expect(result).not.toBeNull();
+ expect(result!.periodStart).toBe(new Date(1712444524000).toISOString());
+ expect(result!.periodEnd).toBe(new Date(1715036524000).toISOString());
+ });
+
+ it("Bug 2 β€” old Stripe-only statuses (trialing, past_due) without period timestamps produce null dates", async () => {
+ mockEntitiesGet.mockResolvedValue({
+ balances: {
+ CREDITS: {
+ remaining: 50,
+ granted: 500,
+ usage: 450,
+ unlimited: false,
+ breakdown: [{ planId: "free", includedGrant: 500 }],
+ },
+ },
+ subscriptions: [
+ {
+ status: "trialing",
+ // No currentPeriodStart/End set
+ },
+ ],
+ });
+
+ // No customer fallback needed for balances, but subscriptions fallback is triggered
+ // because entity has subscriptions with length > 0 but no "active" and no period timestamps
+ const result = await getTeamBalance("team-1");
+ expect(result).not.toBeNull();
+ expect(result!.periodStart).toBeNull();
+ expect(result!.periodEnd).toBeNull();
+ });
+
+ // Bug 3: Entity-scoped lookups may have CREDITS balance but no subscriptions.
+ // Subscriptions live at customer level. The old code only fell back when CREDITS
+ // was missing, leaving billing period dates null.
+ it("Bug 3 β€” falls back to customer-level subscriptions when entity has CREDITS but no subscriptions", async () => {
+ mockEntitiesGet.mockResolvedValue({
+ balances: {
+ CREDITS: {
+ remaining: 99475,
+ granted: 100000,
+ usage: 525,
+ unlimited: false,
+ breakdown: [
+ { planId: "standard", includedGrant: 100000 },
+ { planId: null, includedGrant: 525 },
+ ],
+ },
+ },
+ subscriptions: [], // no entity-level subscriptions
+ });
+
+ mockCustomersGetOrCreate.mockResolvedValue({
+ balances: {
+ CREDITS: {
+ remaining: 461027,
+ granted: 500000,
+ usage: 38973,
+ unlimited: false,
+ breakdown: [{ planId: "growth", includedGrant: 500000 }],
+ },
+ },
+ subscriptions: [
+ {
+ status: "active",
+ currentPeriodStart: 1712444524000,
+ currentPeriodEnd: 1715036524000,
+ },
+ ],
+ });
+
+ const result = await getTeamBalance("team-1");
+
+ expect(result).not.toBeNull();
+ // Should use entity-scoped CREDITS balance (Standard plan, ~100K)
+ expect(result!.remaining).toBe(99475);
+ expect(result!.planCredits).toBe(100000);
+
+ // But should get billing period from customer-level subscriptions
+ expect(result!.periodStart).toBe(new Date(1712444524000).toISOString());
+ expect(result!.periodEnd).toBe(new Date(1715036524000).toISOString());
+
+ // Verify entity was queried first, then customer for subscriptions
+ expect(mockEntitiesGet).toHaveBeenCalledWith({
+ customerId: "org-1",
+ entityId: "team-1",
+ });
+ expect(mockCustomersGetOrCreate).toHaveBeenCalledWith({
+ customerId: "org-1",
+ autoEnablePlanId: "free",
+ });
+ });
+
+ it("Bug 3 β€” does NOT fall back to customer-level when entity has both CREDITS and subscriptions", async () => {
+ mockEntitiesGet.mockResolvedValue({
+ balances: {
+ CREDITS: {
+ remaining: 5000,
+ granted: 10000,
+ usage: 5000,
+ unlimited: false,
+ breakdown: [{ planId: "growth", includedGrant: 10000 }],
+ },
+ },
+ subscriptions: [
+ {
+ status: "active",
+ currentPeriodStart: 1712444524000,
+ currentPeriodEnd: 1715036524000,
+ },
+ ],
+ });
+
+ const result = await getTeamBalance("team-1");
+
+ expect(result).not.toBeNull();
+ expect(result!.remaining).toBe(5000);
+ expect(result!.planCredits).toBe(10000);
+ expect(result!.periodStart).not.toBeNull();
+
+ // Customer-level should NOT be called
+ expect(mockCustomersGetOrCreate).not.toHaveBeenCalled();
+ });
+
+ // Bug 4: planCredits should only sum breakdown entries with planId set.
+ // One-off grants (planId: null) were inflating planCredits.
+ it("Bug 4 β€” excludes one-off grants (planId: null) from planCredits", async () => {
+ mockEntitiesGet.mockResolvedValue({
+ balances: {
+ CREDITS: {
+ remaining: 100525,
+ granted: 100525,
+ usage: 0,
+ unlimited: false,
+ breakdown: [
+ { planId: "standard", includedGrant: 100000 },
+ { planId: null, includedGrant: 500 }, // one-off promo grant
+ { planId: null, includedGrant: 25 }, // another small grant
+ ],
+ },
+ },
+ subscriptions: [
+ {
+ status: "active",
+ currentPeriodStart: 1712444524000,
+ currentPeriodEnd: 1715036524000,
+ },
+ ],
+ });
+
+ const result = await getTeamBalance("team-1");
+
+ expect(result).not.toBeNull();
+ // planCredits should be 100,000 (only from planId: "standard")
+ // NOT 100,525 (which includes the one-off grants)
+ expect(result!.planCredits).toBe(100000);
+ // But remaining/granted reflects the full amount including grants
+ expect(result!.remaining).toBe(100525);
+ expect(result!.granted).toBe(100525);
+ });
+
+ it("Bug 4 β€” sums credits from multiple plans correctly", async () => {
+ mockEntitiesGet.mockResolvedValue({
+ balances: {
+ CREDITS: {
+ remaining: 600500,
+ granted: 600500,
+ usage: 0,
+ unlimited: false,
+ breakdown: [
+ { planId: "growth", includedGrant: 500000 },
+ { planId: "addon-100k", includedGrant: 100000 },
+ { planId: null, includedGrant: 500 }, // promo grant
+ ],
+ },
+ },
+ subscriptions: [
+ {
+ status: "active",
+ currentPeriodStart: 1712444524000,
+ currentPeriodEnd: 1715036524000,
+ },
+ ],
+ });
+
+ const result = await getTeamBalance("team-1");
+
+ expect(result).not.toBeNull();
+ expect(result!.planCredits).toBe(600000);
+ });
+
+ it("Bug 4 β€” falls back to granted when no breakdown is present", async () => {
+ mockEntitiesGet.mockResolvedValue({
+ balances: {
+ CREDITS: {
+ remaining: 1000,
+ granted: 1000,
+ usage: 0,
+ unlimited: false,
+ // No breakdown array
+ },
+ },
+ subscriptions: [
+ {
+ status: "active",
+ currentPeriodStart: 1712444524000,
+ currentPeriodEnd: 1715036524000,
+ },
+ ],
+ });
+
+ const result = await getTeamBalance("team-1");
+
+ expect(result).not.toBeNull();
+ expect(result!.planCredits).toBe(1000);
+ });
+
+ // Full fallback path: entity 404 β†’ customer-level used for everything
+ it("falls back to customer-level entirely when entity returns 404", async () => {
+ mockEntitiesGet.mockRejectedValue(
+ Object.assign(new Error("not found"), { statusCode: 404 }),
+ );
+
+ mockCustomersGetOrCreate.mockResolvedValue({
+ balances: {
+ CREDITS: {
+ remaining: 461027,
+ granted: 500000,
+ usage: 38973,
+ unlimited: false,
+ breakdown: [{ planId: "growth", includedGrant: 500000 }],
+ },
+ },
+ subscriptions: [
+ {
+ status: "active",
+ currentPeriodStart: 1712444524000,
+ currentPeriodEnd: 1715036524000,
+ },
+ ],
+ });
+
+ const result = await getTeamBalance("team-1");
+
+ expect(result).not.toBeNull();
+ expect(result!.remaining).toBe(461027);
+ expect(result!.planCredits).toBe(500000);
+ expect(result!.periodStart).toBe(new Date(1712444524000).toISOString());
+ });
+
+ it("returns null when no CREDITS balance exists", async () => {
+ mockEntitiesGet.mockResolvedValue({
+ balances: {},
+ subscriptions: [],
+ });
+
+ mockCustomersGetOrCreate.mockResolvedValue({
+ balances: {},
+ subscriptions: [],
+ });
+
+ const result = await getTeamBalance("team-1");
+ expect(result).toBeNull();
+ });
+
+ // Bug 5: Yearly plans have currentPeriodStart/End = null on the subscription.
+ // The fix derives billing period from the balance's nextResetAt + reset interval.
+ it("Bug 5 β€” derives billing period from nextResetAt for yearly plans with monthly reset", async () => {
+ const nextResetAt = 1777787407000; // 2026-05-03T05:50:07.000Z
+
+ mockEntitiesGet.mockResolvedValue({
+ balances: {
+ CREDITS: {
+ remaining: 100525,
+ granted: 100525,
+ usage: 0,
+ unlimited: false,
+ nextResetAt,
+ breakdown: [
+ {
+ planId: "standard_yearly",
+ includedGrant: 100000,
+ reset: { interval: "month", resetsAt: nextResetAt },
+ },
+ {
+ planId: null,
+ includedGrant: 525,
+ reset: { interval: "one_off", resetsAt: null },
+ },
+ ],
+ },
+ },
+ subscriptions: [
+ {
+ status: "active",
+ currentPeriodStart: null,
+ currentPeriodEnd: null,
+ },
+ ],
+ });
+
+ const result = await getTeamBalance("team-1");
+
+ expect(result).not.toBeNull();
+ expect(result!.periodEnd).toBe(new Date(nextResetAt).toISOString());
+ // Monthly reset: start should be 1 month before end
+ expect(result!.periodStart).toBe("2026-04-03T05:50:07.000Z");
+ expect(result!.periodEnd).toBe("2026-05-03T05:50:07.000Z");
+ expect(result!.planCredits).toBe(100000);
+ });
+
+ it("Bug 5 β€” derives billing period from nextResetAt for yearly reset interval", async () => {
+ const nextResetAt = 1764741007000; // 2025-12-03T05:50:07.000Z
+
+ mockEntitiesGet.mockResolvedValue({
+ balances: {
+ CREDITS: {
+ remaining: 500000,
+ granted: 500000,
+ usage: 0,
+ unlimited: false,
+ nextResetAt,
+ breakdown: [
+ {
+ planId: "growth_yearly",
+ includedGrant: 500000,
+ reset: { interval: "year", resetsAt: nextResetAt },
+ },
+ ],
+ },
+ },
+ subscriptions: [
+ {
+ status: "active",
+ currentPeriodStart: null,
+ currentPeriodEnd: null,
+ },
+ ],
+ });
+
+ const result = await getTeamBalance("team-1");
+
+ expect(result).not.toBeNull();
+ expect(result!.periodEnd).toBe(new Date(nextResetAt).toISOString());
+ // Yearly reset: start should be 1 year before end
+ expect(result!.periodStart).toBe("2024-12-03T05:50:07.000Z");
+ expect(result!.periodEnd).toBe("2025-12-03T05:50:07.000Z");
+ });
+
+ it("Bug 5 β€” clamps day when month has fewer days (Mar 31 - 1 month = Feb 28)", async () => {
+ const nextResetAt = Date.parse("2026-03-31T12:00:00.000Z");
+
+ mockEntitiesGet.mockResolvedValue({
+ balances: {
+ CREDITS: {
+ remaining: 100000,
+ granted: 100000,
+ usage: 0,
+ unlimited: false,
+ nextResetAt,
+ breakdown: [
+ {
+ planId: "standard_yearly",
+ includedGrant: 100000,
+ reset: { interval: "month", resetsAt: nextResetAt },
+ },
+ ],
+ },
+ },
+ subscriptions: [
+ { status: "active", currentPeriodStart: null, currentPeriodEnd: null },
+ ],
+ });
+
+ const result = await getTeamBalance("team-1");
+
+ expect(result).not.toBeNull();
+ expect(result!.periodStart).toBe("2026-02-28T12:00:00.000Z");
+ expect(result!.periodEnd).toBe("2026-03-31T12:00:00.000Z");
+ });
+
+ it("Bug 5 β€” clamps day for leap year (Mar 31 - 1 month in leap year = Feb 29)", async () => {
+ const nextResetAt = Date.parse("2028-03-31T12:00:00.000Z"); // 2028 is a leap year
+
+ mockEntitiesGet.mockResolvedValue({
+ balances: {
+ CREDITS: {
+ remaining: 100000,
+ granted: 100000,
+ usage: 0,
+ unlimited: false,
+ nextResetAt,
+ breakdown: [
+ {
+ planId: "standard_yearly",
+ includedGrant: 100000,
+ reset: { interval: "month", resetsAt: nextResetAt },
+ },
+ ],
+ },
+ },
+ subscriptions: [
+ { status: "active", currentPeriodStart: null, currentPeriodEnd: null },
+ ],
+ });
+
+ const result = await getTeamBalance("team-1");
+
+ expect(result).not.toBeNull();
+ expect(result!.periodStart).toBe("2028-02-29T12:00:00.000Z");
+ expect(result!.periodEnd).toBe("2028-03-31T12:00:00.000Z");
+ });
+
+ it("Bug 5 β€” clamps day for yearly subtraction (Feb 29 leap year - 1 year = Feb 28)", async () => {
+ const nextResetAt = Date.parse("2028-02-29T12:00:00.000Z"); // 2028 is leap, 2027 is not
+
+ mockEntitiesGet.mockResolvedValue({
+ balances: {
+ CREDITS: {
+ remaining: 500000,
+ granted: 500000,
+ usage: 0,
+ unlimited: false,
+ nextResetAt,
+ breakdown: [
+ {
+ planId: "growth_yearly",
+ includedGrant: 500000,
+ reset: { interval: "year", resetsAt: nextResetAt },
+ },
+ ],
+ },
+ },
+ subscriptions: [
+ { status: "active", currentPeriodStart: null, currentPeriodEnd: null },
+ ],
+ });
+
+ const result = await getTeamBalance("team-1");
+
+ expect(result).not.toBeNull();
+ expect(result!.periodStart).toBe("2027-02-28T12:00:00.000Z");
+ expect(result!.periodEnd).toBe("2028-02-29T12:00:00.000Z");
+ });
+
+ it("Bug 5 β€” leaves both period dates null when nextResetAt exists but no valid interval breakdown", async () => {
+ const nextResetAt = Date.parse("2026-05-03T05:50:07.000Z");
+
+ mockEntitiesGet.mockResolvedValue({
+ balances: {
+ CREDITS: {
+ remaining: 500,
+ granted: 500,
+ usage: 0,
+ unlimited: false,
+ nextResetAt,
+ breakdown: [
+ {
+ planId: null,
+ includedGrant: 500,
+ reset: { interval: "one_off", resetsAt: null },
+ },
+ ],
+ },
+ },
+ subscriptions: [
+ { status: "active", currentPeriodStart: null, currentPeriodEnd: null },
+ ],
+ });
+
+ const result = await getTeamBalance("team-1");
+
+ expect(result).not.toBeNull();
+ // Both should be null β€” not an asymmetric response with only periodEnd set
+ expect(result!.periodStart).toBeNull();
+ expect(result!.periodEnd).toBeNull();
+ });
+
+ it("Bug 5 β€” leaves period null when no nextResetAt and no subscription periods", async () => {
+ mockEntitiesGet.mockResolvedValue({
+ balances: {
+ CREDITS: {
+ remaining: 1000,
+ granted: 1000,
+ usage: 0,
+ unlimited: false,
+ breakdown: [{ planId: "free", includedGrant: 1000 }],
+ },
+ },
+ subscriptions: [
+ {
+ status: "active",
+ currentPeriodStart: null,
+ currentPeriodEnd: null,
+ },
+ ],
+ });
+
+ const result = await getTeamBalance("team-1");
+
+ expect(result).not.toBeNull();
+ expect(result!.periodStart).toBeNull();
+ expect(result!.periodEnd).toBeNull();
+ });
+
+ it("returns correct structure with unlimited credits", async () => {
+ mockEntitiesGet.mockResolvedValue({
+ balances: {
+ CREDITS: {
+ remaining: 0,
+ granted: 0,
+ usage: 12345,
+ unlimited: true,
+ },
+ },
+ subscriptions: [
+ {
+ status: "active",
+ currentPeriodStart: 1712444524000,
+ currentPeriodEnd: 1715036524000,
+ },
+ ],
+ });
+
+ const result = await getTeamBalance("team-1");
+
+ expect(result).not.toBeNull();
+ expect(result!.unlimited).toBe(true);
+ expect(result!.usage).toBe(12345);
+ });
+});
+
+// ---------------------------------------------------------------------------
+// getTeamHistoricalUsage
+// ---------------------------------------------------------------------------
+
describe("getTeamHistoricalUsage", () => {
it("aggregates 90 days of daily usage into calendar-month buckets", async () => {
mockAggregate.mockResolvedValue({
@@ -76,9 +735,7 @@ describe("getTeamHistoricalUsage", () => {
],
});
- await expect(
- getTeamHistoricalUsage("team-1"),
- ).resolves.toEqual([
+ await expect(getTeamHistoricalUsage("team-1")).resolves.toEqual([
{
startDate: "2026-03-01T00:00:00.000Z",
endDate: "2026-04-01T00:00:00.000Z",
@@ -116,9 +773,7 @@ describe("getTeamHistoricalUsage", () => {
],
});
- await expect(
- getTeamHistoricalUsage("team-1"),
- ).resolves.toEqual([
+ await expect(getTeamHistoricalUsage("team-1")).resolves.toEqual([
{
startDate: "2026-04-01T00:00:00.000Z",
endDate: null,
@@ -160,9 +815,7 @@ describe("getTeamHistoricalUsage", () => {
],
});
- await expect(
- getTeamHistoricalUsage("team-1"),
- ).resolves.toEqual([
+ await expect(getTeamHistoricalUsage("team-1")).resolves.toEqual([
{
startDate: "2026-01-01T00:00:00.000Z",
endDate: "2026-02-01T00:00:00.000Z",
@@ -201,9 +854,7 @@ describe("getTeamHistoricalUsageByApiKey", () => {
],
});
- await expect(
- getTeamHistoricalUsageByApiKey("team-1"),
- ).resolves.toEqual([
+ await expect(getTeamHistoricalUsageByApiKey("team-1")).resolves.toEqual([
{
startDate: "2026-03-01T00:00:00.000Z",
endDate: "2026-04-01T00:00:00.000Z",
@@ -252,9 +903,7 @@ describe("getTeamHistoricalUsageByApiKey", () => {
],
});
- await expect(
- getTeamHistoricalUsageByApiKey("team-1"),
- ).resolves.toEqual([
+ await expect(getTeamHistoricalUsageByApiKey("team-1")).resolves.toEqual([
{
startDate: "2026-01-01T00:00:00.000Z",
endDate: "2026-02-01T00:00:00.000Z",
diff --git a/apps/api/src/services/autumn/usage.ts b/apps/api/src/services/autumn/usage.ts
index defd59e58..ad68d7d97 100644
--- a/apps/api/src/services/autumn/usage.ts
+++ b/apps/api/src/services/autumn/usage.ts
@@ -116,9 +116,7 @@ function aggregateHistoricalPeriodsByMonth(list: any[]): HistoricalPeriod[] {
}));
}
-function getGroupedCredits(
- entry: any,
-): Record<string, number> | undefined {
+function getGroupedCredits(entry: any): Record<string, number> | undefined {
return (
entry.groupedValues?.[CREDITS_FEATURE_ID] ??
entry.grouped_values?.[CREDITS_FEATURE_ID]
@@ -213,14 +211,25 @@ export async function getTeamBalance(
// Entity not found β€” fall through to customer-level
}
- // Fall back to customer-level balance if CREDITS feature not present
- if (!balances?.[CREDITS_FEATURE_ID]) {
+ // Fall back to customer-level if CREDITS balance is missing, or if the
+ // entity had no subscriptions (subscriptions live at the customer level
+ // while balances may be entity-scoped).
+ const needCustomerFallback =
+ !balances?.[CREDITS_FEATURE_ID] || !subscriptions?.length;
+
+ if (needCustomerFallback) {
const customer = await autumnClient.customers.getOrCreate({
customerId: orgId,
autoEnablePlanId: "free",
});
- balances = customer?.balances;
- subscriptions = customer?.subscriptions;
+
+ if (!balances?.[CREDITS_FEATURE_ID]) {
+ balances = customer?.balances;
+ }
+ // Always prefer customer-level subscriptions when entity had none
+ if (!subscriptions?.length) {
+ subscriptions = customer?.subscriptions;
+ }
}
const creditBalance = balances?.[CREDITS_FEATURE_ID];
@@ -229,25 +238,71 @@ export async function getTeamBalance(
return null;
}
- // Find the active subscription's billing period
- const activeSub = subscriptions?.find(
- (s: any) =>
- s.status === "active" ||
- s.status === "trialing" ||
- s.status === "past_due",
- );
+ // Find the subscription's billing period.
+ // Autumn uses "active" and "scheduled" statuses (not Stripe's "trialing" /
+ // "past_due"). Prefer an active subscription, but fall back to any
+ // subscription that carries period timestamps so we never return nulls
+ // when the data is actually available.
+ const activeSub =
+ subscriptions?.find((s: any) => s.status === "active") ??
+ subscriptions?.find((s: any) => s.currentPeriodStart != null);
- const periodStartEpoch = activeSub?.currentPeriodStart;
- const periodEndEpoch = activeSub?.currentPeriodEnd;
+ let periodStartEpoch = activeSub?.currentPeriodStart;
+ let periodEndEpoch = activeSub?.currentPeriodEnd;
// Extract plan-only credits from the breakdown (excludes credit packs,
- // auto-recharge, etc.) to preserve backwards compatibility with the old
- // planCredits field semantics.
+ // auto-recharge, one-off grants, etc.) to preserve backwards compatibility
+ // with the old planCredits field semantics.
let planCredits = creditBalance?.granted ?? 0;
const breakdowns: Array<any> | undefined = creditBalance?.breakdown;
+
+ // For yearly plans, Autumn may not populate currentPeriodStart/End on the
+ // subscription. Fall back to the balance's reset schedule: nextResetAt is
+ // the period end, and we derive the start from the reset interval.
+ if (periodStartEpoch == null && periodEndEpoch == null) {
+ const resetAt: number | undefined = creditBalance?.nextResetAt;
+ if (resetAt) {
+ const resetEntry = breakdowns?.find(
+ (b: any) => b.reset?.interval && b.reset.interval !== "one_off",
+ );
+ const interval = resetEntry?.reset?.interval;
+ if (interval === "month" || interval === "year") {
+ periodEndEpoch = resetAt;
+ const endDate = new Date(resetAt);
+ const targetYear =
+ interval === "year"
+ ? endDate.getUTCFullYear() - 1
+ : endDate.getUTCFullYear();
+ const targetMonth =
+ interval === "month"
+ ? endDate.getUTCMonth() - 1
+ : endDate.getUTCMonth();
+
+ // Clamp day to the last day of the target month to avoid overflow
+ // (e.g. Mar 31 minus 1 month β†’ Feb 28, not Mar 3)
+ const lastDay = new Date(
+ Date.UTC(targetYear, targetMonth + 1, 0),
+ ).getUTCDate();
+ const clampedDay = Math.min(endDate.getUTCDate(), lastDay);
+
+ periodStartEpoch = new Date(
+ Date.UTC(
+ targetYear,
+ targetMonth,
+ clampedDay,
+ endDate.getUTCHours(),
+ endDate.getUTCMinutes(),
+ endDate.getUTCSeconds(),
+ endDate.getUTCMilliseconds(),
+ ),
+ ).getTime();
+ }
+ }
+ }
if (breakdowns?.length) {
planCredits = breakdowns.reduce(
- (sum: number, b: any) => sum + (b.includedGrant ?? 0),
+ (sum: number, b: any) =>
+ b.planId != null ? sum + (b.includedGrant ?? 0) : sum,
0,
);
}
@@ -259,11 +314,9 @@ export async function getTeamBalance(
usage: creditBalance?.usage ?? 0,
unlimited: creditBalance?.unlimited ?? false,
periodStart: periodStartEpoch
- ? new Date(periodStartEpoch * 1000).toISOString()
- : null,
- periodEnd: periodEndEpoch
- ? new Date(periodEndEpoch * 1000).toISOString()
+ ? new Date(periodStartEpoch).toISOString()
: null,
+ periodEnd: periodEndEpoch ? new Date(periodEndEpoch).toISOString() : null,
};
}