From 0691fcb2f24de303d5188ce617f9c16533354048 Mon Sep 17 00:00:00 2001
From: Jacek <jacek@clerk.dev>
Date: Tue, 27 Jan 2026 15:19:29 -0600
Subject: [PATCH 1/4] refactor(shared): rename useBillingHookEnabled to
 useBillingIsEnabled

Update semantics so calling without 'for' param returns true if either
user or organization billing is enabled, rather than defaulting to user.
---
 .../react/billing/useInitializePaymentMethod.tsx |  4 ++--
 .../shared/src/react/billing/useStripeLoader.tsx |  4 ++--
 .../react/hooks/createBillingPaginatedHook.tsx   |  4 ++--
 ...lingHookEnabled.ts => useBillingIsEnabled.ts} | 16 +++++++++++-----
 .../src/react/hooks/usePaymentAttemptQuery.tsx   |  4 ++--
 .../src/react/hooks/usePlanDetailsQuery.tsx      |  4 ++--
 .../shared/src/react/hooks/useStatementQuery.tsx |  4 ++--
 .../shared/src/react/hooks/useSubscription.tsx   |  4 ++--
 8 files changed, 25 insertions(+), 19 deletions(-)
 rename packages/shared/src/react/hooks/{useBillingHookEnabled.ts => useBillingIsEnabled.ts} (64%)

diff --git a/packages/shared/src/react/billing/useInitializePaymentMethod.tsx b/packages/shared/src/react/billing/useInitializePaymentMethod.tsx
index 1bf0f2164e2..8e1f08aa343 100644
--- a/packages/shared/src/react/billing/useInitializePaymentMethod.tsx
+++ b/packages/shared/src/react/billing/useInitializePaymentMethod.tsx
@@ -5,7 +5,7 @@ import { defineKeepPreviousDataFn } from '../clerk-rq/keep-previous-data';
 import { useClerkQueryClient } from '../clerk-rq/use-clerk-query-client';
 import { useClerkQuery } from '../clerk-rq/useQuery';
 import { useOrganizationContext, useUserContext } from '../contexts';
-import { useBillingHookEnabled } from '../hooks/useBillingHookEnabled';
+import { useBillingIsEnabled } from '../hooks/useBillingIsEnabled';
 import { useClearQueriesOnSignOut } from '../hooks/useClearQueriesOnSignOut';
 
 type InitializePaymentMethodOptions = {
@@ -27,7 +27,7 @@ function useInitializePaymentMethod(options?: InitializePaymentMethodOptions): U
 
   const resource = forType === 'organization' ? organization : user;
 
-  const billingEnabled = useBillingHookEnabled(options);
+  const billingEnabled = useBillingIsEnabled(options);
 
   const stableKey = 'billing-payment-method-initialize';
   const authenticated = true;
diff --git a/packages/shared/src/react/billing/useStripeLoader.tsx b/packages/shared/src/react/billing/useStripeLoader.tsx
index 59dee615f6b..7b6d9e097c7 100644
--- a/packages/shared/src/react/billing/useStripeLoader.tsx
+++ b/packages/shared/src/react/billing/useStripeLoader.tsx
@@ -3,7 +3,7 @@ import { useMemo } from 'react';
 
 import { defineKeepPreviousDataFn } from '../clerk-rq/keep-previous-data';
 import { useClerkQuery } from '../clerk-rq/useQuery';
-import { useBillingHookEnabled } from '../hooks/useBillingHookEnabled';
+import { useBillingIsEnabled } from '../hooks/useBillingIsEnabled';
 import type { UseStripeClerkLibsResult } from './useStripeClerkLibs';
 
 type StripeLoaderOptions = {
@@ -24,7 +24,7 @@ function useStripeLoader(options: StripeLoaderOptions): UseStripeLoaderResult {
     return ['stripe-sdk', { externalGatewayId, stripePublishableKey }] as const;
   }, [externalGatewayId, stripePublishableKey]);
 
-  const billingEnabled = useBillingHookEnabled({ authenticated: true });
+  const billingEnabled = useBillingIsEnabled({ authenticated: true });
 
   const isEnabled = Boolean(stripeClerkLibs && externalGatewayId && stripePublishableKey) && billingEnabled;
 
diff --git a/packages/shared/src/react/hooks/createBillingPaginatedHook.tsx b/packages/shared/src/react/hooks/createBillingPaginatedHook.tsx
index 9d658db2969..fa5d9f37ae5 100644
--- a/packages/shared/src/react/hooks/createBillingPaginatedHook.tsx
+++ b/packages/shared/src/react/hooks/createBillingPaginatedHook.tsx
@@ -9,7 +9,7 @@ import {
 import type { ResourceCacheStableKey } from '../stable-keys';
 import type { PagesOrInfiniteOptions, PaginatedHookConfig, PaginatedResources } from '../types';
 import { createCacheKeys } from './createCacheKeys';
-import { useBillingHookEnabled } from './useBillingHookEnabled';
+import { useBillingIsEnabled } from './useBillingIsEnabled';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -106,7 +106,7 @@ export function createBillingPaginatedHook<TResource extends ClerkResource, TPar
 
     const isForOrganization = safeFor === 'organization';
 
-    const billingEnabled = useBillingHookEnabled({
+    const billingEnabled = useBillingIsEnabled({
       for: safeFor,
       enabled: externalEnabled,
       authenticated: !options?.unauthenticated,
diff --git a/packages/shared/src/react/hooks/useBillingHookEnabled.ts b/packages/shared/src/react/hooks/useBillingIsEnabled.ts
similarity index 64%
rename from packages/shared/src/react/hooks/useBillingHookEnabled.ts
rename to packages/shared/src/react/hooks/useBillingIsEnabled.ts
index dc477267e59..82894dd51af 100644
--- a/packages/shared/src/react/hooks/useBillingHookEnabled.ts
+++ b/packages/shared/src/react/hooks/useBillingIsEnabled.ts
@@ -4,7 +4,7 @@ import { useClerkInstanceContext, useOrganizationContext, useUserContext } from
 /**
  * @internal
  */
-export function useBillingHookEnabled(params?: { for?: ForPayerType; enabled?: boolean; authenticated?: boolean }) {
+export function useBillingIsEnabled(params?: { for?: ForPayerType; enabled?: boolean; authenticated?: boolean }) {
   const clerk = useClerkInstanceContext();
 
   const enabledFromParam = params?.enabled ?? true;
@@ -15,11 +15,17 @@ export function useBillingHookEnabled(params?: { for?: ForPayerType; enabled?: b
   const user = useUserContext();
   const { organization } = useOrganizationContext();
 
-  const isOrganization = params?.for === 'organization';
-  const billingEnabled = isOrganization
-    ? environment?.commerceSettings.billing.organization.enabled
-    : environment?.commerceSettings.billing.user.enabled;
+  const userBillingEnabled = environment?.commerceSettings.billing.user.enabled;
+  const orgBillingEnabled = environment?.commerceSettings.billing.organization.enabled;
+
+  const billingEnabled =
+    params?.for === 'organization'
+      ? orgBillingEnabled
+      : params?.for === 'user'
+        ? userBillingEnabled
+        : userBillingEnabled || orgBillingEnabled;
 
+  const isOrganization = params?.for === 'organization';
   const requireUserAndOrganizationWhenAuthenticated =
     (params?.authenticated ?? true) ? (isOrganization ? Boolean(organization?.id) : true) && Boolean(user?.id) : true;
 
diff --git a/packages/shared/src/react/hooks/usePaymentAttemptQuery.tsx b/packages/shared/src/react/hooks/usePaymentAttemptQuery.tsx
index 7a59fc5b282..140d62386c3 100644
--- a/packages/shared/src/react/hooks/usePaymentAttemptQuery.tsx
+++ b/packages/shared/src/react/hooks/usePaymentAttemptQuery.tsx
@@ -1,7 +1,7 @@
 import { defineKeepPreviousDataFn } from '../clerk-rq/keep-previous-data';
 import { useClerkQuery } from '../clerk-rq/useQuery';
 import { useClerkInstanceContext, useOrganizationContext, useUserContext } from '../contexts';
-import { useBillingHookEnabled } from './useBillingHookEnabled';
+import { useBillingIsEnabled } from './useBillingIsEnabled';
 import { useClearQueriesOnSignOut } from './useClearQueriesOnSignOut';
 import { usePaymentAttemptQueryCacheKeys } from './usePaymentAttemptQuery.shared';
 import type { PaymentAttemptQueryResult, UsePaymentAttemptQueryParams } from './usePaymentAttemptQuery.types';
@@ -25,7 +25,7 @@ function usePaymentAttemptQuery(params: UsePaymentAttemptQueryParams): PaymentAt
     for: forType,
   });
 
-  const billingEnabled = useBillingHookEnabled(params);
+  const billingEnabled = useBillingIsEnabled(params);
 
   const queryEnabled = Boolean(paymentAttemptId) && billingEnabled;
 
diff --git a/packages/shared/src/react/hooks/usePlanDetailsQuery.tsx b/packages/shared/src/react/hooks/usePlanDetailsQuery.tsx
index c2a7ec96cbd..9bffbc0e578 100644
--- a/packages/shared/src/react/hooks/usePlanDetailsQuery.tsx
+++ b/packages/shared/src/react/hooks/usePlanDetailsQuery.tsx
@@ -1,7 +1,7 @@
 import { defineKeepPreviousDataFn } from '../clerk-rq/keep-previous-data';
 import { useClerkQuery } from '../clerk-rq/useQuery';
 import { useClerkInstanceContext } from '../contexts';
-import { useBillingHookEnabled } from './useBillingHookEnabled';
+import { useBillingIsEnabled } from './useBillingIsEnabled';
 import { usePlanDetailsQueryCacheKeys } from './usePlanDetailsQuery.shared';
 import type { PlanDetailsQueryResult, UsePlanDetailsQueryParams } from './usePlanDetailsQuery.types';
 
@@ -16,7 +16,7 @@ export function __internal_usePlanDetailsQuery(params: UsePlanDetailsQueryParams
 
   const { queryKey } = usePlanDetailsQueryCacheKeys({ planId: targetPlanId });
 
-  const billingEnabled = useBillingHookEnabled({
+  const billingEnabled = useBillingIsEnabled({
     authenticated: false,
   });
 
diff --git a/packages/shared/src/react/hooks/useStatementQuery.tsx b/packages/shared/src/react/hooks/useStatementQuery.tsx
index 25f8b4a3908..d230308b4bb 100644
--- a/packages/shared/src/react/hooks/useStatementQuery.tsx
+++ b/packages/shared/src/react/hooks/useStatementQuery.tsx
@@ -1,7 +1,7 @@
 import { defineKeepPreviousDataFn } from '../clerk-rq/keep-previous-data';
 import { useClerkQuery } from '../clerk-rq/useQuery';
 import { useClerkInstanceContext, useOrganizationContext, useUserContext } from '../contexts';
-import { useBillingHookEnabled } from './useBillingHookEnabled';
+import { useBillingIsEnabled } from './useBillingIsEnabled';
 import { useClearQueriesOnSignOut } from './useClearQueriesOnSignOut';
 import { useStatementQueryCacheKeys } from './useStatementQuery.shared';
 import type { StatementQueryResult, UseStatementQueryParams } from './useStatementQuery.types';
@@ -25,7 +25,7 @@ function useStatementQuery(params: UseStatementQueryParams = {}): StatementQuery
     for: forType,
   });
 
-  const billingEnabled = useBillingHookEnabled(params);
+  const billingEnabled = useBillingIsEnabled(params);
 
   const queryEnabled = Boolean(statementId) && billingEnabled;
 
diff --git a/packages/shared/src/react/hooks/useSubscription.tsx b/packages/shared/src/react/hooks/useSubscription.tsx
index 90a531750bd..74b9f3f6c5e 100644
--- a/packages/shared/src/react/hooks/useSubscription.tsx
+++ b/packages/shared/src/react/hooks/useSubscription.tsx
@@ -10,7 +10,7 @@ import {
   useOrganizationContext,
   useUserContext,
 } from '../contexts';
-import { useBillingHookEnabled } from './useBillingHookEnabled';
+import { useBillingIsEnabled } from './useBillingIsEnabled';
 import { useClearQueriesOnSignOut } from './useClearQueriesOnSignOut';
 import { useSubscriptionCacheKeys } from './useSubscription.shared';
 import type { SubscriptionResult, UseSubscriptionParams } from './useSubscription.types';
@@ -27,7 +27,7 @@ export function useSubscription(params?: UseSubscriptionParams): SubscriptionRes
   const user = useUserContext();
   const { organization } = useOrganizationContext();
 
-  const billingEnabled = useBillingHookEnabled(params);
+  const billingEnabled = useBillingIsEnabled(params);
 
   const recordedRef = useRef(false);
   useEffect(() => {

From eb270991cdd3b40e591c7be1bbc998140a9864e2 Mon Sep 17 00:00:00 2001
From: Jacek <jacek@clerk.dev>
Date: Tue, 27 Jan 2026 15:25:18 -0600
Subject: [PATCH 2/4] chore: empty changeset

---
 .changeset/fiery-carrots-call.md | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 .changeset/fiery-carrots-call.md

diff --git a/.changeset/fiery-carrots-call.md b/.changeset/fiery-carrots-call.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/fiery-carrots-call.md
@@ -0,0 +1,2 @@
+---
+---

From fd8786a8d6ea00553602feab2fd82c6ea32726f6 Mon Sep 17 00:00:00 2001
From: Jacek <jacek@clerk.dev>
Date: Tue, 27 Jan 2026 16:16:05 -0600
Subject: [PATCH 3/4] test(shared): update billing tests for new semantics

---
 .../billing/__tests__/useInitializePaymentMethod.spec.tsx      | 3 ++-
 .../shared/src/react/hooks/__tests__/useSubscription.spec.tsx  | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/shared/src/react/billing/__tests__/useInitializePaymentMethod.spec.tsx b/packages/shared/src/react/billing/__tests__/useInitializePaymentMethod.spec.tsx
index fa4dde7b99b..14e6a23cbab 100644
--- a/packages/shared/src/react/billing/__tests__/useInitializePaymentMethod.spec.tsx
+++ b/packages/shared/src/react/billing/__tests__/useInitializePaymentMethod.spec.tsx
@@ -66,8 +66,9 @@ describe('useInitializePaymentMethod', () => {
     expect(result.current.initializePaymentMethod).toBeInstanceOf(Function);
   });
 
-  it('does not fetch when billing disabled for user', () => {
+  it('does not fetch when billing disabled', () => {
     mockClerk.__internal_environment.commerceSettings.billing.user.enabled = false;
+    mockClerk.__internal_environment.commerceSettings.billing.organization.enabled = false;
 
     const { result } = renderHook(() => useInitializePaymentMethod(), { wrapper });
 
diff --git a/packages/shared/src/react/hooks/__tests__/useSubscription.spec.tsx b/packages/shared/src/react/hooks/__tests__/useSubscription.spec.tsx
index 06bdf71cc85..ed3d5738e20 100644
--- a/packages/shared/src/react/hooks/__tests__/useSubscription.spec.tsx
+++ b/packages/shared/src/react/hooks/__tests__/useSubscription.spec.tsx
@@ -57,8 +57,9 @@ describe('useSubscription', () => {
     defaultQueryClient.client.clear();
   });
 
-  it('does not fetch when billing disabled for user', () => {
+  it('does not fetch when billing disabled', () => {
     mockClerk.__internal_environment.commerceSettings.billing.user.enabled = false;
+    mockClerk.__internal_environment.commerceSettings.billing.organization.enabled = false;
 
     const { result } = renderHook(() => useSubscription(), { wrapper });
 

From bc50c7cf95bd8deedcd1d7739d1f9e89b4bb7ccc Mon Sep 17 00:00:00 2001
From: Jacek <jacek@clerk.dev>
Date: Fri, 30 Jan 2026 15:05:37 -0600
Subject: [PATCH 4/4] chore: update changeset to major

---
 .changeset/fiery-carrots-call.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.changeset/fiery-carrots-call.md b/.changeset/fiery-carrots-call.md
index a845151cc84..30bdce97121 100644
--- a/.changeset/fiery-carrots-call.md
+++ b/.changeset/fiery-carrots-call.md
@@ -1,2 +1,5 @@
 ---
+'@clerk/shared': major
 ---
+
+Rename internal `useBillingHookEnabled` to `useBillingIsEnabled` with improved semantics for authentication and organization context checks.