From 895b011b1af718a1c88420bb03af87f59b1afad3 Mon Sep 17 00:00:00 2001
From: Sarah Soutoul <sarah@clerk.dev>
Date: Tue, 25 Nov 2025 16:57:59 -0600
Subject: [PATCH 1/2] Hide billing types not needed in Typedoc

---
 packages/shared/src/react/hooks/useAPIKeys.rq.tsx           | 6 ++++--
 packages/shared/src/react/hooks/useAPIKeys.swr.tsx          | 6 ++++--
 .../shared/src/react/hooks/usePaymentAttemptQuery.types.ts  | 4 ++--
 .../shared/src/react/hooks/usePlanDetailsQuery.types.ts     | 4 ++--
 packages/shared/src/react/hooks/useStatementQuery.types.ts  | 4 ++--
 5 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/packages/shared/src/react/hooks/useAPIKeys.rq.tsx b/packages/shared/src/react/hooks/useAPIKeys.rq.tsx
index 05b8962e90f..068c139a9c2 100644
--- a/packages/shared/src/react/hooks/useAPIKeys.rq.tsx
+++ b/packages/shared/src/react/hooks/useAPIKeys.rq.tsx
@@ -7,7 +7,7 @@ import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
- * @interface
+ * @internal
  */
 export type UseAPIKeysParams = PaginatedHookConfig<
   GetAPIKeysParams & {
@@ -21,7 +21,7 @@ export type UseAPIKeysParams = PaginatedHookConfig<
 >;
 
 /**
- * @interface
+ * @internal
  */
 export type UseAPIKeysReturn<T extends UseAPIKeysParams> = PaginatedResources<
   APIKeyResource,
@@ -29,6 +29,8 @@ export type UseAPIKeysReturn<T extends UseAPIKeysParams> = PaginatedResources<
 >;
 
 /**
+ * @internal
+ *
  * The `useAPIKeys()` hook provides access to paginated API keys for the current user or organization.
  *
  * @example
diff --git a/packages/shared/src/react/hooks/useAPIKeys.swr.tsx b/packages/shared/src/react/hooks/useAPIKeys.swr.tsx
index 6696bb49b92..dc7037ab621 100644
--- a/packages/shared/src/react/hooks/useAPIKeys.swr.tsx
+++ b/packages/shared/src/react/hooks/useAPIKeys.swr.tsx
@@ -10,7 +10,7 @@ import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
- * @interface
+ * @internal
  */
 export type UseAPIKeysParams = PaginatedHookConfig<
   GetAPIKeysParams & {
@@ -24,7 +24,7 @@ export type UseAPIKeysParams = PaginatedHookConfig<
 >;
 
 /**
- * @interface
+ * @internal
  */
 export type UseAPIKeysReturn<T extends UseAPIKeysParams> = PaginatedResources<
   APIKeyResource,
@@ -32,6 +32,8 @@ export type UseAPIKeysReturn<T extends UseAPIKeysParams> = PaginatedResources<
 >;
 
 /**
+ * @internal
+ *
  * The `useAPIKeys()` hook provides access to paginated API keys for the current user or organization.
  *
  * @example
diff --git a/packages/shared/src/react/hooks/usePaymentAttemptQuery.types.ts b/packages/shared/src/react/hooks/usePaymentAttemptQuery.types.ts
index 5e8fb16ad92..9c1dd976333 100644
--- a/packages/shared/src/react/hooks/usePaymentAttemptQuery.types.ts
+++ b/packages/shared/src/react/hooks/usePaymentAttemptQuery.types.ts
@@ -2,7 +2,7 @@ import type { ClerkAPIResponseError } from '../../error';
 import type { BillingPaymentResource, ForPayerType } from '../../types';
 
 /**
- * @interface
+ * @internal
  */
 export type UsePaymentAttemptQueryParams = {
   /**
@@ -30,7 +30,7 @@ export type UsePaymentAttemptQueryParams = {
 };
 
 /**
- * @interface
+ * @internal
  */
 export type PaymentAttemptQueryResult = {
   /**
diff --git a/packages/shared/src/react/hooks/usePlanDetailsQuery.types.ts b/packages/shared/src/react/hooks/usePlanDetailsQuery.types.ts
index 9dfae918964..653e4229a42 100644
--- a/packages/shared/src/react/hooks/usePlanDetailsQuery.types.ts
+++ b/packages/shared/src/react/hooks/usePlanDetailsQuery.types.ts
@@ -2,7 +2,7 @@ import type { ClerkAPIResponseError } from '../../errors/clerkApiResponseError';
 import type { BillingPlanResource } from '../../types';
 
 /**
- * @interface
+ * @internal
  */
 export type UsePlanDetailsQueryParams = {
   /**
@@ -28,7 +28,7 @@ export type UsePlanDetailsQueryParams = {
 };
 
 /**
- * @interface
+ * @internal
  */
 export type PlanDetailsQueryResult = {
   /**
diff --git a/packages/shared/src/react/hooks/useStatementQuery.types.ts b/packages/shared/src/react/hooks/useStatementQuery.types.ts
index fe7f6174aec..f6302024101 100644
--- a/packages/shared/src/react/hooks/useStatementQuery.types.ts
+++ b/packages/shared/src/react/hooks/useStatementQuery.types.ts
@@ -1,7 +1,7 @@
 import type { BillingStatementResource, ClerkAPIResponseError, ForPayerType } from '../../types';
 
 /**
- * @interface
+ * @internal
  */
 export type UseStatementQueryParams = {
   /**
@@ -29,7 +29,7 @@ export type UseStatementQueryParams = {
 };
 
 /**
- * @interface
+ * @internal
  */
 export type StatementQueryResult = {
   /**

From 5fe543cab4760025e9c3c5bb752e3b56e87b7450 Mon Sep 17 00:00:00 2001
From: Sarah Soutoul <sarah@clerk.dev>
Date: Tue, 25 Nov 2025 17:04:38 -0600
Subject: [PATCH 2/2] Add changeset

---
 .changeset/gold-wasps-dress.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/gold-wasps-dress.md

diff --git a/.changeset/gold-wasps-dress.md b/.changeset/gold-wasps-dress.md
new file mode 100644
index 00000000000..d4619b5e95c
--- /dev/null
+++ b/.changeset/gold-wasps-dress.md
@@ -0,0 +1,5 @@
+---
+'@clerk/shared': minor
+---
+
+Hide billing types through @internal tag