chore(clerk-js,types): Replace payerType[] with forPayerType (#6342)

panteliselef · web-flow · commit 10e10605b18a · 2025-07-18T19:16:31.000Z
diff --git a/.changeset/proud-pianos-attack.md b/.changeset/proud-pianos-attack.md
@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/types': minor
+---
+
+[Billing Beta] Replace `payerType[]` with `forPayerType` typed as `'org' | 'user'`.
diff --git a/.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap b/.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap
@@ -32,6 +32,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/commerce-initialized-payment-source-resource.mdx",
   "types/commerce-money-json.mdx",
   "types/commerce-money.mdx",
+  "types/commerce-payer-type.mdx",
   "types/commerce-payment-charge-type.mdx",
   "types/commerce-payment-json.mdx",
   "types/commerce-payment-resource.mdx",
@@ -51,7 +52,6 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/commerce-statement-status.mdx",
   "types/commerce-statement-totals-json.mdx",
   "types/commerce-statement-totals.mdx",
-  "types/commerce-subscriber-type.mdx",
   "types/commerce-subscription-json.mdx",
   "types/commerce-subscription-plan-period.mdx",
   "types/commerce-subscription-resource.mdx",
diff --git a/packages/clerk-js/src/core/resources/CommercePlan.ts b/packages/clerk-js/src/core/resources/CommercePlan.ts
@@ -1,4 +1,4 @@
-import type { CommercePlanJSON, CommercePlanJSONSnapshot, CommercePlanResource } from '@clerk/types';
+import type { CommercePayerType, CommercePlanJSON, CommercePlanJSONSnapshot, CommercePlanResource } from '@clerk/types';
 
 import { BaseResource, CommerceFeature } from './internal';
 
@@ -17,7 +17,7 @@ export class CommercePlan extends BaseResource implements CommercePlanResource {
   isDefault!: boolean;
   isRecurring!: boolean;
   hasBaseFee!: boolean;
-  payerType!: string[];
+  forPayerType!: CommercePayerType;
   publiclyVisible!: boolean;
   slug!: string;
   avatarUrl!: string;
@@ -47,7 +47,7 @@ export class CommercePlan extends BaseResource implements CommercePlanResource {
     this.isDefault = data.is_default;
     this.isRecurring = data.is_recurring;
     this.hasBaseFee = data.has_base_fee;
-    this.payerType = data.payer_type;
+    this.forPayerType = data.for_payer_type;
     this.publiclyVisible = data.publicly_visible;
     this.slug = data.slug;
     this.avatarUrl = data.avatar_url;
@@ -73,7 +73,7 @@ export class CommercePlan extends BaseResource implements CommercePlanResource {
       is_default: this.isDefault,
       is_recurring: this.isRecurring,
       has_base_fee: this.hasBaseFee,
-      payer_type: this.payerType,
+      for_payer_type: this.forPayerType,
       publicly_visible: this.publiclyVisible,
       slug: this.slug,
       avatar_url: this.avatarUrl,
diff --git a/packages/clerk-js/src/ui/components/Plans/PlanDetails.tsx b/packages/clerk-js/src/ui/components/Plans/PlanDetails.tsx
@@ -58,7 +58,7 @@ const PlanDetailsInternal = ({
   const hasFeatures = features.length > 0;
 
   return (
-    <SubscriberTypeContext.Provider value={plan.payerType[0] as 'user' | 'org'}>
+    <SubscriberTypeContext.Provider value={plan.forPayerType}>
       <Drawer.Header
         sx={t =>
           !hasFeatures
diff --git a/packages/clerk-js/src/ui/contexts/components/SubscriberType.ts b/packages/clerk-js/src/ui/contexts/components/SubscriberType.ts
@@ -1,9 +1,10 @@
+import type { CommercePayerType } from '@clerk/types';
 import { createContext, useContext } from 'react';
 
 const DEFAUlT = 'user';
-export const SubscriberTypeContext = createContext<'user' | 'org' | undefined>(DEFAUlT);
+export const SubscriberTypeContext = createContext<CommercePayerType | undefined>(DEFAUlT);
 
-export const useSubscriberTypeContext = () => useContext(SubscriberTypeContext) || DEFAUlT;
+export const useSubscriberTypeContext = (): CommercePayerType => useContext(SubscriberTypeContext) || DEFAUlT;
 
 export const useSubscriberTypeLocalizationRoot = () => {
   const subscriberType = useSubscriberTypeContext();
diff --git a/packages/types/src/clerk.ts b/packages/types/src/clerk.ts
@@ -23,8 +23,8 @@ import type { ClientResource } from './client';
 import type {
   CommerceBillingNamespace,
   CommerceCheckoutResource,
+  CommercePayerType,
   CommercePlanResource,
-  CommerceSubscriberType,
   CommerceSubscriptionPlanPeriod,
   ConfirmCheckoutParams,
 } from './commerce';
@@ -1806,7 +1806,7 @@ export type __internal_CheckoutProps = {
   appearance?: CheckoutTheme;
   planId?: string;
   planPeriod?: CommerceSubscriptionPlanPeriod;
-  subscriberType?: CommerceSubscriberType;
+  subscriberType?: CommercePayerType;
   onSubscriptionComplete?: () => void;
   portalId?: string;
   portalRoot?: PortalRoot;
@@ -1843,7 +1843,7 @@ export type __internal_SubscriptionDetailsProps = {
    * If `org` is provided, the subscription details will be displayed for the active organization.
    * @default 'user'
    */
-  for?: CommerceSubscriberType;
+  for?: CommercePayerType;
   appearance?: SubscriptionDetailsTheme;
   onSubscriptionCancel?: () => void;
   portalId?: string;
diff --git a/packages/types/src/commerce.ts b/packages/types/src/commerce.ts
@@ -85,7 +85,7 @@ export interface CommerceBillingNamespace {
  * <ClerkProvider clerkJsVersion="x.x.x" />
  * ```
  */
-export type CommerceSubscriberType = 'org' | 'user';
+export type CommercePayerType = 'org' | 'user';
 
 /**
  * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
@@ -214,7 +214,7 @@ export type GetPlansParams = ClerkPaginationParams<{
    * <ClerkProvider clerkJsVersion="x.x.x" />
    * ```
    */
-  for?: CommerceSubscriberType;
+  for?: CommercePayerType;
 }>;
 
 /**
@@ -356,18 +356,8 @@ export interface CommercePlanResource extends ClerkResource {
    *
    * Each plan is exclusively created for either individual users or organizations,
    * and cannot be used interchangeably.
-   *
-   * @type {['user'] | ['org']}
-   * @example
-   * ```ts
-   * // For a user plan
-   * payerType: ['user']
-   *
-   * // For an organization plan
-   * payerType: ['org']
-   * ```
    */
-  payerType: string[];
+  forPayerType: CommercePayerType;
   /**
    * @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.
diff --git a/packages/types/src/json.ts b/packages/types/src/json.ts
@@ -4,6 +4,7 @@
 
 import type { APIKeysSettingsJSON } from './apiKeysSettings';
 import type {
+  CommercePayerType,
   CommercePaymentChargeType,
   CommercePaymentSourceStatus,
   CommercePaymentStatus,
@@ -643,23 +644,7 @@ export interface CommercePlanJSON extends ClerkResourceJSON {
   is_default: boolean;
   is_recurring: boolean;
   has_base_fee: boolean;
-  /**
-   * Specifies the subscriber type this plan is designed for.
-   *
-   * Each plan is exclusively created for either individual users or organizations,
-   * and cannot be used interchangeably.
-   *
-   * @type {['user'] | ['org']}
-   * @example
-   * ```ts
-   * // For a user plan
-   * payer_type: ['user']
-   *
-   * // For an organization plan
-   * payer_type: ['org']
-   * ```
-   */
-  payer_type: string[];
+  for_payer_type: CommercePayerType;
   publicly_visible: boolean;
   slug: string;
   avatar_url: string;
