feat(shared,clerk-js): Accept enabled option in Billing hooks

.changeset/heavy-suns-divide.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Fixes a bug where billing hooks would attempt to fetch billing information for an organization member with insufficient permissions, resulting in a 403 error.

.changeset/thin-swans-punch.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': minor
+---
+
+Billing hooks now accept a `{ enabled: boolean }` option, that controls the whether or not a request will fire.

packages/clerk-js/src/ui/components/OrganizationProfile/__tests__/OrganizationProfile.test.tsx

@@ -85,8 +85,8 @@ describe('OrganizationProfile', () => {
 
       render(<OrganizationProfile />, { wrapper });
       await waitFor(() => expect(screen.queryByText('Billing')).toBeNull());
-      expect(fixtures.clerk.billing.getSubscription).toHaveBeenCalled();
-      expect(fixtures.clerk.billing.getStatements).toHaveBeenCalled();
+      expect(fixtures.clerk.billing.getSubscription).not.toHaveBeenCalled();
+      expect(fixtures.clerk.billing.getStatements).not.toHaveBeenCalled();
     });
 
     it('does not include Billing when missing billing permission even with paid plans', async () => {
@@ -109,9 +109,8 @@ describe('OrganizationProfile', () => {
       render(<OrganizationProfile />, { wrapper });
       await waitFor(() => expect(screen.queryByText('Billing')).toBeNull());
 
-      // TODO(@RQ_MIGRATION): Offer a way to disable these, because they fire unnecessary requests.
-      expect(fixtures.clerk.billing.getSubscription).toHaveBeenCalled();
-      expect(fixtures.clerk.billing.getStatements).toHaveBeenCalled();
+      expect(fixtures.clerk.billing.getSubscription).not.toHaveBeenCalled();
+      expect(fixtures.clerk.billing.getStatements).not.toHaveBeenCalled();
     });
     it('does not include Billing when organization billing is disabled', async () => {
       const { wrapper, fixtures } = await createFixtures(f => {

packages/clerk-js/src/ui/components/PricingTable/__tests__/PricingTable.test.tsx

@@ -398,6 +398,11 @@ describe('PricingTable - plans visibility', () => {
       // Should show plans when signed out
       expect(getByRole('heading', { name: 'Test Plan' })).toBeVisible();
     });
+
+    // Ensure API args reflect user context by default
+    expect(fixtures.clerk.billing.getPlans).toHaveBeenCalledWith(expect.objectContaining({ for: 'user' }));
+    // Signed-out users should not fetch subscriptions
+    expect(fixtures.clerk.billing.getSubscription).not.toHaveBeenCalled();
   });
 
   it('shows no plans when user is signed in but subscription is null', async () => {
@@ -517,7 +522,15 @@ describe('PricingTable - plans visibility', () => {
     const { wrapper, fixtures, props } = await createFixtures(f => {
       f.withBilling();
       f.withOrganizations();
-      f.withUser({ email_addresses: ['test@clerk.com'], organization_memberships: ['Org1'] });
+      f.withUser({
+        email_addresses: ['test@clerk.com'],
+        organization_memberships: [
+          {
+            name: 'Org1',
+            permissions: ['org:sys_billing:manage'],
+          },
+        ],
+      });
     });
 
     // Set legacy prop via context provider
@@ -572,7 +585,15 @@ describe('PricingTable - plans visibility', () => {
     const { wrapper, fixtures, props } = await createFixtures(f => {
       f.withBilling();
       f.withOrganizations();
-      f.withUser({ email_addresses: ['test@clerk.com'], organization_memberships: ['Org1'] });
+      f.withUser({
+        email_addresses: ['test@clerk.com'],
+        organization_memberships: [
+          {
+            name: 'Org1',
+            permissions: ['org:sys_billing:read'],
+          },
+        ],
+      });
     });
 
     // Set new prop via context provider

packages/clerk-js/src/ui/contexts/components/Plans.tsx

@@ -5,6 +5,7 @@ import {
   __experimental_useStatements,
   __experimental_useSubscription,
   useClerk,
+  useOrganization,
   useSession,
 } from '@clerk/shared/react';
 import type {
@@ -15,6 +16,7 @@ import type {
 } from '@clerk/shared/types';
 import { useCallback, useMemo } from 'react';
 
+import { useProtect } from '@/ui/common/Gate';
 import { getClosestProfileScrollBox } from '@/ui/utils/getClosestProfileScrollBox';
 
 import type { LocalizationKey } from '../../localization';
@@ -28,44 +30,42 @@ export function normalizeFormatted(formatted: string) {
   return formatted.endsWith('.00') ? formatted.slice(0, -3) : formatted;
 }
 
-// TODO(@COMMERCE): Rename payment sources to payment methods at the API level
-export const usePaymentMethods = () => {
+const useBillingHookParams = () => {
   const subscriberType = useSubscriberTypeContext();
-  return __experimental_usePaymentMethods({
+  const { organization } = useOrganization();
+  const allowBillingRoutes = useProtect(
+    has =>
+      has({
+        permission: 'org:sys_billing:read',
+      }) || has({ permission: 'org:sys_billing:manage' }),
+  );
+
+  return {
     for: subscriberType,
-    initialPage: 1,
-    pageSize: 10,
     keepPreviousData: true,
-  });
+    // If the user is in an organization, only fetch billing data if they have the necessary permissions
+    enabled: subscriberType === 'organization' ? Boolean(organization) && allowBillingRoutes : true,
+  };
+};
+
+export const usePaymentMethods = () => {
+  const params = useBillingHookParams();
+  return __experimental_usePaymentMethods(params);
 };
 
 export const usePaymentAttempts = () => {
-  const subscriberType = useSubscriberTypeContext();
-  return __experimental_usePaymentAttempts({
-    for: subscriberType,
-    initialPage: 1,
-    pageSize: 10,
-    keepPreviousData: true,
-  });
+  const params = useBillingHookParams();
+  return __experimental_usePaymentAttempts(params);
 };
 
-export const useStatements = (params?: { mode: 'cache' }) => {
-  const subscriberType = useSubscriberTypeContext();
-  return __experimental_useStatements({
-    for: subscriberType,
-    initialPage: 1,
-    pageSize: 10,
-    keepPreviousData: true,
-    __experimental_mode: params?.mode,
-  });
+export const useStatements = (externalParams?: { mode: 'cache' }) => {
+  const params = useBillingHookParams();
+  return __experimental_useStatements({ ...params, __experimental_mode: externalParams?.mode });
 };
 
 export const useSubscription = () => {
-  const subscriberType = useSubscriberTypeContext();
-  const subscription = __experimental_useSubscription({
-    for: subscriberType,
-    keepPreviousData: true,
-  });
+  const params = useBillingHookParams();
+  const subscription = __experimental_useSubscription(params);
   const subscriptionItems = useMemo(
     () => subscription.data?.subscriptionItems || [],
     [subscription.data?.subscriptionItems],
@@ -85,6 +85,7 @@ export const usePlans = (params?: { mode: 'cache' }) => {
     initialPage: 1,
     pageSize: 50,
     keepPreviousData: true,
+    enabled: true,
     __experimental_mode: params?.mode,
   });
 };

packages/shared/src/react/hooks/__tests__/createBillingPaginatedHook.spec.tsx

@@ -98,6 +98,26 @@ describe('createBillingPaginatedHook', () => {
     expect(result.current.isFetching).toBe(false);
   });
 
+  it('does not fetch when enabled is false', () => {
+    const { result } = renderHook(() => useDummyAuth({ initialPage: 1, pageSize: 4, enabled: false }), { wrapper });
+
+    expect(useFetcherMock).toHaveBeenCalledWith('user');
+
+    expect(fetcherMock).not.toHaveBeenCalled();
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.isFetching).toBe(false);
+    expect(result.current.data).toEqual([]);
+  });
+
+  it('fetches when enabled is true', async () => {
+    const { result } = renderHook(() => useDummyAuth({ initialPage: 1, pageSize: 4, enabled: true }), { wrapper });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(useFetcherMock).toHaveBeenCalledWith('user');
+    expect(fetcherMock).toHaveBeenCalled();
+    expect(fetcherMock.mock.calls[0][0]).toStrictEqual({ initialPage: 1, pageSize: 4 });
+  });
+
   it('authenticated hook: does not fetch when user is null', () => {
     mockUser = null;
 

packages/shared/src/react/hooks/createBillingPaginatedHook.tsx

@@ -43,14 +43,23 @@ export function createBillingPaginatedHook<TResource extends ClerkResource, TPar
   useFetcher,
   options,
 }: BillingHookConfig<TResource, TParams>) {
-  type HookParams = PaginatedHookConfig<PagesOrInfiniteOptions> & {
+  type HookParams = PaginatedHookConfig<
+    PagesOrInfiniteOptions & {
+      /**
+       * If `true`, a request will be triggered when the hook is mounted.
+       *
+       * @default true
+       */
+      enabled?: boolean;
+    }
+  > & {
     for?: ForPayerType;
   };
 
   return function useBillingHook<T extends HookParams>(
     params?: T,
   ): PaginatedResources<TResource, T extends { infinite: true } ? true : false> {
-    const { for: _for, ...paginationParams } = params || ({} as Partial<T>);
+    const { for: _for, enabled: externalEnabled, ...paginationParams } = params || ({} as Partial<T>);
 
     const safeFor = _for || 'user';
 
@@ -90,7 +99,7 @@ export function createBillingPaginatedHook<TResource extends ClerkResource, TPar
       ? environment?.commerceSettings.billing.organization.enabled
       : environment?.commerceSettings.billing.user.enabled;
 
-    const isEnabled = !!hookParams && clerk.loaded && !!billingEnabled;
+    const isEnabled = !!hookParams && clerk.loaded && !!billingEnabled && (externalEnabled ?? true);
 
     const result = usePagesOrInfinite<TParams, ClerkPaginatedResponse<TResource>>(
       (hookParams || {}) as TParams,

packages/shared/src/react/hooks/useSubscription.rq.tsx

@@ -12,7 +12,7 @@ import {
 } from '../contexts';
 import type { SubscriptionResult, UseSubscriptionParams } from './useSubscription.types';
 
-const hookName = 'useSubscription';
+const HOOK_NAME = 'useSubscription';
 
 /**
  * This is the new implementation of useSubscription using React Query.
@@ -21,7 +21,7 @@ const hookName = 'useSubscription';
  * @internal
  */
 export function useSubscription(params?: UseSubscriptionParams): SubscriptionResult {
-  useAssertWrappedByClerkProvider(hookName);
+  useAssertWrappedByClerkProvider(HOOK_NAME);
 
   const clerk = useClerkInstanceContext();
   const user = useUserContext();
@@ -30,7 +30,7 @@ export function useSubscription(params?: UseSubscriptionParams): SubscriptionRes
   // @ts-expect-error `__unstable__environment` is not typed
   const environment = clerk.__unstable__environment as unknown as EnvironmentResource | null | undefined;
 
-  clerk.telemetry?.record(eventMethodCalled(hookName));
+  clerk.telemetry?.record(eventMethodCalled(HOOK_NAME));
 
   const isOrganization = params?.for === 'organization';
   const billingEnabled = isOrganization
@@ -49,14 +49,16 @@ export function useSubscription(params?: UseSubscriptionParams): SubscriptionRes
     ];
   }, [user?.id, isOrganization, organization?.id]);
 
+  const queriesEnabled = Boolean(user?.id && billingEnabled) && (params?.enabled ?? true);
+
   const query = useClerkQuery({
     queryKey,
     queryFn: ({ queryKey }) => {
       const obj = queryKey[1] as { args: { orgId?: string } };
       return clerk.billing.getSubscription(obj.args);
     },
     staleTime: 1_000 * 60,
-    enabled: Boolean(user?.id && billingEnabled) && ((params as any)?.enabled ?? true),
+    enabled: queriesEnabled,
     // TODO(@RQ_MIGRATION): Add support for keepPreviousData
   });
 

packages/shared/src/react/hooks/useSubscription.swr.tsx

@@ -35,9 +35,10 @@ export function useSubscription(params?: UseSubscriptionParams): SubscriptionRes
   const billingEnabled = isOrganization
     ? environment?.commerceSettings.billing.organization.enabled
     : environment?.commerceSettings.billing.user.enabled;
+  const isEnabled = (params?.enabled ?? true) && billingEnabled;
 
   const swr = useSWR(
-    billingEnabled
+    isEnabled
       ? {
           type: 'commerce-subscription',
           userId: user?.id,

packages/shared/src/react/hooks/useSubscription.types.ts

@@ -7,6 +7,12 @@ export type UseSubscriptionParams = {
    * Defaults to false.
    */
   keepPreviousData?: boolean;
+  /**
+   * If `true`, a request will be triggered when the hook is mounted.
+   *
+   * @default true
+   */
+  enabled?: boolean;
 };
 
 export type SubscriptionResult = {