chore(shared,clerk-js): Introduce experimental usePlans (#6327)

panteliselef · web-flow · commit a329836a6c64 · 2025-07-17T14:43:53.000Z
diff --git a/.changeset/eight-socks-lead.md b/.changeset/eight-socks-lead.md
@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+[Billing Beta] Update `clerk.billing.getPlans()` to return paginated data and introduce the `usePlans()` hook.
diff --git a/packages/clerk-js/src/core/modules/commerce/CommerceBilling.ts b/packages/clerk-js/src/core/modules/commerce/CommerceBilling.ts
@@ -6,7 +6,6 @@ import type {
   CommercePaymentResource,
   CommercePlanJSON,
   CommercePlanResource,
-  CommerceProductJSON,
   CommerceStatementJSON,
   CommerceStatementResource,
   CommerceSubscriptionJSON,
@@ -29,15 +28,21 @@ import {
 } from '../../resources/internal';
 
 export class CommerceBilling implements CommerceBillingNamespace {
-  getPlans = async (params?: GetPlansParams): Promise<CommercePlanResource[]> => {
-    const { data: products } = (await BaseResource._fetch({
-      path: `/commerce/products`,
+  getPlans = async (params?: GetPlansParams): Promise<ClerkPaginatedResponse<CommercePlanResource>> => {
+    const { for: forParam, ...safeParams } = params || {};
+    const searchParams = { ...safeParams, payer_type: forParam || 'user' };
+    return await BaseResource._fetch({
+      path: `/commerce/plans`,
       method: 'GET',
-      search: { payerType: params?.subscriberType || '' },
-    })) as unknown as ClerkPaginatedResponse<CommerceProductJSON>;
+      search: convertPageToOffsetSearchParams(searchParams),
+    }).then(res => {
+      const { data: plans, total_count } = res as unknown as ClerkPaginatedResponse<CommercePlanJSON>;
 
-    const defaultProduct = products.find(product => product.is_default);
-    return defaultProduct?.plans.map(plan => new CommercePlan(plan)) || [];
+      return {
+        total_count,
+        data: plans.map(plan => new CommercePlan(plan)),
+      };
+    });
   };
 
   getPlan = async (params: { id: string }): Promise<CommercePlanResource> => {
diff --git a/packages/clerk-js/src/ui/contexts/components/Plans.tsx b/packages/clerk-js/src/ui/contexts/components/Plans.tsx
@@ -1,12 +1,11 @@
 import {
   __experimental_usePaymentAttempts,
   __experimental_usePaymentMethods,
+  __experimental_usePlans,
   __experimental_useStatements,
   __experimental_useSubscriptionItems,
   useClerk,
-  useOrganization,
   useSession,
-  useUser,
 } from '@clerk/shared/react';
 import type {
   Appearance,
@@ -15,30 +14,13 @@ import type {
   CommerceSubscriptionResource,
 } from '@clerk/types';
 import { useCallback, useMemo } from 'react';
-import useSWR from 'swr';
 
 import { getClosestProfileScrollBox } from '@/ui/utils/getClosestProfileScrollBox';
 
 import type { LocalizationKey } from '../../localization';
 import { localizationKeys } from '../../localization';
 import { useSubscriberTypeContext } from './SubscriberType';
 
-const dedupeOptions = {
-  dedupingInterval: 1_000 * 60, // 1 minute,
-  keepPreviousData: true,
-};
-
-export const usePaymentSourcesCacheKey = () => {
-  const { organization } = useOrganization();
-  const { user } = useUser();
-  const subscriberType = useSubscriberTypeContext();
-
-  return {
-    key: `commerce-payment-sources`,
-    resourceId: subscriberType === 'org' ? organization?.id : user?.id,
-  };
-};
-
 // TODO(@COMMERCE): Rename payment sources to payment methods at the API level
 export const usePaymentMethods = () => {
   const subscriberType = useSubscriberTypeContext();
@@ -82,18 +64,16 @@ export const useSubscriptions = () => {
   });
 };
 
-export const usePlans = () => {
-  const { billing } = useClerk();
+export const usePlans = (params?: { mode: 'cache' }) => {
   const subscriberType = useSubscriberTypeContext();
 
-  return useSWR(
-    {
-      key: `commerce-plans`,
-      args: { subscriberType },
-    },
-    ({ args }) => billing.getPlans(args),
-    dedupeOptions,
-  );
+  return __experimental_usePlans({
+    for: subscriberType === 'org' ? 'organization' : 'user',
+    initialPage: 1,
+    pageSize: 50,
+    keepPreviousData: true,
+    __experimental_mode: params?.mode,
+  });
 };
 
 type HandleSelectPlanProps = {
@@ -125,10 +105,7 @@ export const usePlansContext = () => {
   const { data: subscriptions, revalidate: revalidateSubscriptions } = useSubscriptions();
 
   // Invalidates cache but does not fetch immediately
-  const { data: plans, mutate: mutatePlans } = useSWR<Awaited<ReturnType<typeof clerk.billing.getPlans>>>({
-    key: `commerce-plans`,
-    args: { subscriberType },
-  });
+  const { data: plans, revalidate: revalidatePlans } = usePlans({ mode: 'cache' });
 
   // Invalidates cache but does not fetch immediately
   const { revalidate: revalidateStatements } = useStatements({ mode: 'cache' });
@@ -138,10 +115,10 @@ export const usePlansContext = () => {
   const revalidateAll = useCallback(() => {
     // Revalidate the plans and subscriptions
     void revalidateSubscriptions();
-    void mutatePlans();
+    void revalidatePlans();
     void revalidateStatements();
     void revalidatePaymentSources();
-  }, [revalidateSubscriptions, mutatePlans, revalidateStatements, revalidatePaymentSources]);
+  }, [revalidateSubscriptions, revalidatePlans, revalidateStatements, revalidatePaymentSources]);
 
   // should the default plan be shown as active
   const isDefaultPlanImplicitlyActiveOrUpcoming = useMemo(() => {
diff --git a/packages/shared/src/react/hooks/createCommerceHook.tsx b/packages/shared/src/react/hooks/createCommerceHook.tsx
@@ -19,6 +19,9 @@ type CommerceHookConfig<TResource extends ClerkResource, TParams extends PagesOr
   useFetcher: (
     param: 'organization' | 'user',
   ) => ((params: TParams) => Promise<ClerkPaginatedResponse<TResource>>) | undefined;
+  options?: {
+    unauthenticated?: boolean;
+  };
 };
 
 /**
@@ -39,6 +42,7 @@ export function createCommerceHook<TResource extends ClerkResource, TParams exte
   hookName,
   resourceType,
   useFetcher,
+  options,
 }: CommerceHookConfig<TResource, TParams>) {
   type HookParams = PaginatedHookConfig<PagesOrInfiniteOptions> & {
     for: 'organization' | 'user';
@@ -76,7 +80,7 @@ export function createCommerceHook<TResource extends ClerkResource, TParams exte
             ...(_for === 'organization' ? { orgId: organization?.id } : {}),
           } as TParams);
 
-    const isClerkLoaded = !!(clerk.loaded && user);
+    const isClerkLoaded = !!(clerk.loaded && (options?.unauthenticated ? true : user));
 
     const isEnabled = !!hookParams && isClerkLoaded;
 
diff --git a/packages/shared/src/react/hooks/index.ts b/packages/shared/src/react/hooks/index.ts
@@ -12,4 +12,5 @@ export { useStatements as __experimental_useStatements } from './useStatements';
 export { usePaymentAttempts as __experimental_usePaymentAttempts } from './usePaymentAttempts';
 export { usePaymentMethods as __experimental_usePaymentMethods } from './usePaymentMethods';
 export { useSubscriptionItems as __experimental_useSubscriptionItems } from './useSubscriptionItems';
+export { usePlans as __experimental_usePlans } from './usePlans';
 export { useCheckout as __experimental_useCheckout } from './useCheckout';
diff --git a/packages/shared/src/react/hooks/usePlans.tsx b/packages/shared/src/react/hooks/usePlans.tsx
@@ -0,0 +1,19 @@
+import type { CommercePlanResource, GetPlansParams } from '@clerk/types';
+
+import { useClerkInstanceContext } from '../contexts';
+import { createCommerceHook } from './createCommerceHook';
+
+/**
+ * @internal
+ */
+export const usePlans = createCommerceHook<CommercePlanResource, GetPlansParams>({
+  hookName: 'usePlans',
+  resourceType: 'commerce-plans',
+  useFetcher: _for => {
+    const clerk = useClerkInstanceContext();
+    return params => clerk.billing.getPlans({ ...params, for: _for === 'organization' ? 'org' : 'user' });
+  },
+  options: {
+    unauthenticated: true,
+  },
+});
diff --git a/packages/types/src/commerce.ts b/packages/types/src/commerce.ts
@@ -34,7 +34,7 @@ export interface CommerceBillingNamespace {
    * <ClerkProvider clerkJsVersion="x.x.x" />
    * ```
    */
-  getPlans: (params?: GetPlansParams) => Promise<CommercePlanResource[]>;
+  getPlans: (params?: GetPlansParams) => Promise<ClerkPaginatedResponse<CommercePlanResource>>;
 
   /**
    * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
@@ -205,7 +205,7 @@ export interface CommerceProductResource extends ClerkResource {
  * <ClerkProvider clerkJsVersion="x.x.x" />
  * ```
  */
-export interface GetPlansParams {
+export type GetPlansParams = ClerkPaginationParams<{
   /**
    * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
    * It is advised to pin the SDK version and the clerk-js version to a specific version to avoid breaking changes.
@@ -214,8 +214,8 @@ export interface GetPlansParams {
    * <ClerkProvider clerkJsVersion="x.x.x" />
    * ```
    */
-  subscriberType?: CommerceSubscriberType;
-}
+  for?: CommerceSubscriberType;
+}>;
 
 /**
  * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
