feat(backend, clerk-js): Update the supported API version to 2025-11-10 (#7095)

Author: panteliselef

.changeset/hot-jars-smell.md

@@ -0,0 +1,19 @@
+---
+'@clerk/shared': minor
+'@clerk/agent-toolkit': minor
+'@clerk/astro': minor
+'@clerk/backend': minor
+'@clerk/chrome-extension': minor
+'@clerk/clerk-expo': minor
+'@clerk/clerk-js': minor
+'@clerk/fastify': minor
+'@clerk/nextjs': minor
+'@clerk/nuxt': minor
+'@clerk/clerk-react': minor
+'@clerk/react-router': minor
+'@clerk/tanstack-react-start': minor
+'@clerk/types': minor
+'@clerk/vue': minor
+---
+
+Update the supported API version to `2025-11-10`.

integration/tests/pricing-table.test.ts

@@ -1,3 +1,4 @@
+import type { Locator } from '@playwright/test';
 import { expect, test } from '@playwright/test';
 
 import { appConfigs } from '../presets';
@@ -278,14 +279,22 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withBilling] })('pricing tabl
       // Verify checkout shows trial details
       await expect(u.po.checkout.root.getByText('Checkout')).toBeVisible();
       await expect(u.po.checkout.root.getByText('Free trial')).toBeVisible();
-      await expect(u.po.checkout.root.getByText('Total Due after')).toBeVisible();
+      const title = /^Total Due after trial ends in \d+ days$/i;
+      await expect(matchLineItem(u.po.checkout.root, title, '$999.00')).toBeVisible();
 
       await u.po.checkout.fillTestCard();
       await u.po.checkout.clickPayOrSubscribe();
 
       await expect(u.po.checkout.root.getByText(/Trial.*successfully.*started/i)).toBeVisible({
         timeout: 15_000,
       });
+
+      const footer = u.po.checkout.root.locator('.cl-drawerFooter');
+      await expect(matchLineItem(footer, 'Total paid', '$0.00')).toBeVisible();
+      await expect(matchLineItem(footer, 'Trial ends on')).toBeVisible();
+      await expect(matchLineItem(footer, 'Payment method', 'Visa ⋯ 4242')).toBeVisible();
+      expect(await countLineItems(footer)).toBe(3);
+
       await u.po.checkout.confirmAndContinue();
 
       await u.po.page.goToRelative('/pricing-table');
@@ -344,12 +353,18 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withBilling] })('pricing tabl
       // Verify checkout shows trial details
       await expect(u.po.checkout.root.getByText('Checkout')).toBeVisible();
       await expect(u.po.checkout.root.getByText('Free trial')).toBeHidden();
-      await expect(u.po.checkout.root.getByText('Total Due after')).toBeHidden();
-      await expect(u.po.checkout.root.getByText('Total Due Today')).toBeVisible();
+
+      await expect(matchLineItem(u.po.checkout.root, 'Total Due after')).toBeHidden();
+      await expect(matchLineItem(u.po.checkout.root, 'Subtotal', '$999.00')).toBeVisible();
+      await expect(matchLineItem(u.po.checkout.root, 'Total Due Today', '$999.00')).toBeVisible();
+      expect(await countLineItems(u.po.checkout.root)).toBe(3);
 
       await u.po.checkout.root.getByRole('button', { name: /^pay\s\$/i }).waitFor({ state: 'visible' });
       await u.po.checkout.clickPayOrSubscribe();
-      await expect(u.po.page.getByText('Payment was successful!')).toBeVisible();
+      await expect(u.po.checkout.root.getByText('Payment was successful!')).toBeVisible();
+      await expect(matchLineItem(footer, 'Total paid', '$999.00')).toBeVisible();
+      await expect(matchLineItem(footer, 'Payment method', 'Visa ⋯ 4242')).toBeVisible();
+      expect(await countLineItems(footer)).toBe(2);
       await u.po.checkout.confirmAndContinue();
 
       await u.po.page.goToRelative('/user');
@@ -877,3 +892,34 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withBilling] })('pricing tabl
     });
   });
 });
+
+/**
+ * Helper to match a line item by its title and optionally its description.
+ * Line items are rendered as Clerk LineItems components with element descriptors:
+ * - .cl-lineItemsTitle contains the title
+ * - .cl-lineItemsDescription contains the description (immediately following the title)
+ */
+function matchLineItem(root: Locator, title: string | RegExp, description?: string | RegExp): Locator {
+  // Find the title element using the Clerk-generated class
+  const titleElement = root.locator('.cl-lineItemsTitle').filter({ hasText: title });
+
+  // If no description is provided, return the title element
+  if (description === undefined) {
+    return titleElement;
+  }
+
+  // Get the next sibling description element using the Clerk-generated class
+  const descriptionElement = titleElement
+    .locator('xpath=following-sibling::*[1][contains(@class, "cl-lineItemsDescription")]')
+    .filter({ hasText: description });
+
+  return descriptionElement;
+}
+
+/**
+ * Helper to count the number of line items within a given root element.
+ * Line items are rendered as Clerk LineItems components where each .cl-lineItemsTitle represents a line item.
+ */
+async function countLineItems(root: Locator): Promise<number> {
+  return await root.locator('.cl-lineItemsTitle').count();
+}

packages/backend/src/api/resources/CommercePlan.ts

@@ -1,4 +1,4 @@
-import type { BillingMoneyAmount } from '@clerk/types';
+import type { BillingMoneyAmount, BillingMoneyAmountJSON } from '@clerk/shared/types';
 
 import { Feature } from './Feature';
 import type { BillingPlanJSON } from './JSON';
@@ -14,10 +14,6 @@ export class BillingPlan {
      * The unique identifier for the plan.
      */
     readonly id: string,
-    /**
-     * The ID of the product the plan belongs to.
-     */
-    readonly productId: string,
     /**
      * The name of the plan.
      */
@@ -29,7 +25,7 @@ export class BillingPlan {
     /**
      * The description of the plan.
      */
-    readonly description: string | undefined,
+    readonly description: string | null,
     /**
      * Whether the plan is the default plan.
      */
@@ -53,11 +49,11 @@ export class BillingPlan {
     /**
      * The annual fee of the plan.
      */
-    readonly annualFee: BillingMoneyAmount,
+    readonly annualFee: BillingMoneyAmount | null,
     /**
      * The annual fee of the plan on a monthly basis.
      */
-    readonly annualMonthlyFee: BillingMoneyAmount,
+    readonly annualMonthlyFee: BillingMoneyAmount | null,
     /**
      * The type of payer for the plan.
      */
@@ -69,20 +65,25 @@ export class BillingPlan {
   ) {}
 
   static fromJSON(data: BillingPlanJSON): BillingPlan {
-    const formatAmountJSON = (fee: BillingPlanJSON['fee']) => {
-      return {
-        amount: fee.amount,
-        amountFormatted: fee.amount_formatted,
-        currency: fee.currency,
-        currencySymbol: fee.currency_symbol,
-      };
+    const formatAmountJSON = <T extends BillingMoneyAmountJSON | null>(
+      fee: T,
+    ): T extends null ? null : BillingMoneyAmount => {
+      return (
+        fee
+          ? {
+              amount: fee.amount,
+              amountFormatted: fee.amount_formatted,
+              currency: fee.currency,
+              currencySymbol: fee.currency_symbol,
+            }
+          : null
+      ) as T extends null ? null : BillingMoneyAmount;
     };
     return new BillingPlan(
       data.id,
-      data.product_id,
       data.name,
       data.slug,
-      data.description,
+      data.description ?? null,
       data.is_default,
       data.is_recurring,
       data.has_base_fee,
@@ -91,7 +92,7 @@ export class BillingPlan {
       formatAmountJSON(data.annual_fee),
       formatAmountJSON(data.annual_monthly_fee),
       data.for_payer_type,
-      data.features.map(feature => Feature.fromJSON(feature)),
+      (data.features ?? []).map(feature => Feature.fromJSON(feature)),
     );
   }
 }

packages/backend/src/api/resources/CommerceSubscription.ts

@@ -73,7 +73,7 @@ export class BillingSubscription {
       data.updated_at,
       data.active_at ?? null,
       data.past_due_at ?? null,
-      data.subscription_items.map(item => BillingSubscriptionItem.fromJSON(item)),
+      (data.subscription_items ?? []).map(item => BillingSubscriptionItem.fromJSON(item)),
       nextPayment,
       data.eligible_for_free_trial ?? false,
     );

packages/backend/src/api/resources/CommerceSubscriptionItem.ts

@@ -29,20 +29,23 @@ export class BillingSubscriptionItem {
     /**
      * The next payment information.
      */
-    readonly nextPayment: {
-      /**
-       * The amount of the next payment.
-       */
-      amount: number;
-      /**
-       * Unix timestamp (milliseconds) of when the next payment is scheduled.
-       */
-      date: number;
-    } | null,
+    readonly nextPayment:
+      | {
+          /**
+           * The amount of the next payment.
+           */
+          amount: number;
+          /**
+           * Unix timestamp (milliseconds) of when the next payment is scheduled.
+           */
+          date: number;
+        }
+      | null
+      | undefined,
     /**
      * The current amount for the subscription item.
      */
-    readonly amount: BillingMoneyAmount | null | undefined,
+    readonly amount: BillingMoneyAmount | undefined,
     /**
      * The plan associated with this subscription item.
      */
@@ -78,15 +81,15 @@ export class BillingSubscriptionItem {
     /**
      * The payer ID.
      */
-    readonly payerId: string,
+    readonly payerId: string | undefined,
     /**
      * Whether this subscription item is currently in a free trial period.
      */
     readonly isFreeTrial?: boolean,
     /**
      * The lifetime amount paid for this subscription item.
      */
-    readonly lifetimePaid?: BillingMoneyAmount | null,
+    readonly lifetimePaid?: BillingMoneyAmount,
   ) {}
 
   static fromJSON(data: BillingSubscriptionItemJSON): BillingSubscriptionItem {
@@ -111,7 +114,7 @@ export class BillingSubscriptionItem {
       data.plan_period,
       data.period_start,
       data.next_payment,
-      formatAmountJSON(data.amount),
+      formatAmountJSON(data.amount) ?? undefined,
       data.plan ? BillingPlan.fromJSON(data.plan) : null,
       data.plan_id ?? null,
       data.created_at,
@@ -122,7 +125,7 @@ export class BillingSubscriptionItem {
       data.ended_at,
       data.payer_id,
       data.is_free_trial,
-      formatAmountJSON(data.lifetime_paid),
+      formatAmountJSON(data.lifetime_paid) ?? undefined,
     );
   }
 }

packages/backend/src/api/resources/Feature.ts

@@ -18,18 +18,18 @@ export class Feature {
     /**
      * The description of the feature.
      */
-    readonly description: string,
+    readonly description: string | null,
     /**
      * The URL-friendly identifier of the feature.
      */
     readonly slug: string,
     /**
      * The URL of the feature's avatar image.
      */
-    readonly avatarUrl: string,
+    readonly avatarUrl: string | null,
   ) {}
 
   static fromJSON(data: FeatureJSON): Feature {
-    return new Feature(data.id, data.name, data.description, data.slug, data.avatar_url);
+    return new Feature(data.id, data.name, data.description ?? null, data.slug, data.avatar_url ?? null);
   }
 }

packages/backend/src/api/resources/JSON.ts

@@ -834,9 +834,9 @@ interface BillingTotalsJSON {
 export interface FeatureJSON extends ClerkResourceJSON {
   object: typeof ObjectType.Feature;
   name: string;
-  description: string;
+  description?: string | null;
   slug: string;
-  avatar_url: string;
+  avatar_url?: string | null;
 }
 
 /**
@@ -845,19 +845,18 @@ export interface FeatureJSON extends ClerkResourceJSON {
 export interface BillingPlanJSON extends ClerkResourceJSON {
   object: typeof ObjectType.BillingPlan;
   id: string;
-  product_id: string;
   name: string;
   slug: string;
-  description?: string;
+  description: string | null;
   is_default: boolean;
   is_recurring: boolean;
   has_base_fee: boolean;
   publicly_visible: boolean;
   fee: BillingMoneyAmountJSON;
-  annual_fee: BillingMoneyAmountJSON;
-  annual_monthly_fee: BillingMoneyAmountJSON;
+  annual_fee: BillingMoneyAmountJSON | null;
+  annual_monthly_fee: BillingMoneyAmountJSON | null;
   for_payer_type: 'org' | 'user';
-  features: FeatureJSON[];
+  features?: FeatureJSON[];
 }
 
 type BillingSubscriptionItemStatus =
@@ -877,7 +876,7 @@ export interface BillingSubscriptionItemJSON extends ClerkResourceJSON {
   object: typeof ObjectType.BillingSubscriptionItem;
   status: BillingSubscriptionItemStatus;
   plan_period: 'month' | 'annual';
-  payer_id: string;
+  payer_id?: string;
   period_start: number;
   period_end: number | null;
   is_free_trial?: boolean;
@@ -886,12 +885,12 @@ export interface BillingSubscriptionItemJSON extends ClerkResourceJSON {
   updated_at: number;
   canceled_at: number | null;
   past_due_at: number | null;
-  lifetime_paid: BillingMoneyAmountJSON;
-  next_payment: {
+  lifetime_paid: BillingMoneyAmountJSON | null;
+  next_payment?: {
     amount: number;
     date: number;
   } | null;
-  amount: BillingMoneyAmountJSON | null;
+  amount: BillingMoneyAmountJSON;
   plan?: BillingPlanJSON | null;
   plan_id?: string | null;
 }

packages/backend/src/constants.ts

@@ -3,7 +3,7 @@ export const API_VERSION = 'v1';
 
 export const USER_AGENT = `${PACKAGE_NAME}@${PACKAGE_VERSION}`;
 export const MAX_CACHE_LAST_UPDATED_AT_SECONDS = 5 * 60;
-export const SUPPORTED_BAPI_VERSION = '2025-04-10';
+export const SUPPORTED_BAPI_VERSION = '2025-11-10';
 
 const Attributes = {
   AuthToken: '__clerkAuthToken',

packages/backend/src/tokens/__tests__/handshake.test.ts

@@ -427,7 +427,7 @@ describe('HandshakeService', () => {
 
       // Verify all required parameters are present
       expect(url.searchParams.get('redirect_url')).toBeDefined();
-      expect(url.searchParams.get('__clerk_api_version')).toBe('2025-04-10');
+      expect(url.searchParams.get('__clerk_api_version')).toBe('2025-11-10');
       expect(url.searchParams.get(constants.QueryParameters.SuffixedCookies)).toMatch(/^(true|false)$/);
       expect(url.searchParams.get(constants.QueryParameters.HandshakeReason)).toBe('test-reason');
     });

packages/clerk-js/bundlewatch.config.json

@@ -24,7 +24,7 @@
     { "path": "./dist/waitlist*.js", "maxSize": "1.5KB" },
     { "path": "./dist/keylessPrompt*.js", "maxSize": "6.5KB" },
     { "path": "./dist/pricingTable*.js", "maxSize": "4.02KB" },
-    { "path": "./dist/checkout*.js", "maxSize": "8.8KB" },
+    { "path": "./dist/checkout*.js", "maxSize": "8.82KB" },
     { "path": "./dist/up-billing-page*.js", "maxSize": "3.0KB" },
     { "path": "./dist/op-billing-page*.js", "maxSize": "3.0KB" },
     { "path": "./dist/up-plans-page*.js", "maxSize": "1.0KB" },