fix(clerk-js,types,localizations): Adjust invalid plan change alert wording (#6248)

aeliox · panteliselef · web-flow · commit 3f1270db86a2 · 2025-07-16T15:16:12.000-07:00
Co-authored-by: panteliselef &lt;panteliselef@outlook.com&gt;
diff --git a/.changeset/orange-doors-notice.md b/.changeset/orange-doors-notice.md
@@ -0,0 +1,7 @@
+---
+'@clerk/localizations': minor
+'@clerk/clerk-js': patch
+'@clerk/types': minor
+---
+
+Improve invalid plan change callout for monthly-only plans 
diff --git a/integration/tests/pricing-table.test.ts b/integration/tests/pricing-table.test.ts
@@ -351,7 +351,7 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withBilling] })('pricing tabl
         page
           .locator('.cl-checkout-root')
           .getByText(
-            'You cannot subscribe to this plan by paying monthly. To subscribe to this plan, you need to choose to pay annually',
+            'You cannot subscribe to this plan by paying monthly. To subscribe to this plan, you need to choose to pay annually.',
           ),
       ).toBeVisible();
 
diff --git a/packages/clerk-js/bundlewatch.config.json b/packages/clerk-js/bundlewatch.config.json
@@ -23,7 +23,7 @@
     { "path": "./dist/waitlist*.js", "maxSize": "1.5KB" },
     { "path": "./dist/keylessPrompt*.js", "maxSize": "6.5KB" },
     { "path": "./dist/pricingTable*.js", "maxSize": "4.02KB" },
-    { "path": "./dist/checkout*.js", "maxSize": "8.4KB" },
+    { "path": "./dist/checkout*.js", "maxSize": "8.45KB" },
     { "path": "./dist/up-billing-page*.js", "maxSize": "3.0KB" },
     { "path": "./dist/op-billing-page*.js", "maxSize": "3.0KB" },
     { "path": "./dist/up-plans-page*.js", "maxSize": "1.0KB" },
diff --git a/packages/clerk-js/src/ui/components/Checkout/parts.tsx b/packages/clerk-js/src/ui/components/Checkout/parts.tsx
@@ -48,6 +48,11 @@ export const InvalidPlanScreen = () => {
     return _error?.meta?.plan;
   }, [error]);
 
+  const isPlanUpgradePossible = useMemo(() => {
+    const _error = error?.errors.find(e => e.code === 'invalid_plan_change');
+    return _error?.meta?.isPlanUpgradePossible || false;
+  }, [error]);
+
   if (!planFromError) {
     return null;
   }
@@ -85,7 +90,11 @@ export const InvalidPlanScreen = () => {
           <Alert
             variant='info'
             colorScheme='info'
-            title={localizationKeys('commerce.cannotSubscribeMonthly')}
+            title={
+              isPlanUpgradePossible
+                ? localizationKeys('commerce.cannotSubscribeMonthly')
+                : localizationKeys('commerce.cannotSubscribeUnrecoverable')
+            }
           />
         </Box>
       </Flex>
diff --git a/packages/localizations/src/en-US.ts b/packages/localizations/src/en-US.ts
@@ -69,6 +69,8 @@ export const enUS: LocalizationResource = {
     cancelSubscriptionTitle: 'Cancel {{plan}} Subscription?',
     cannotSubscribeMonthly:
       'You cannot subscribe to this plan by paying monthly. To subscribe to this plan, you need to choose to pay annually.',
+    cannotSubscribeUnrecoverable:
+      'You cannot subscribe to this plan. Your existing subscription is more expensive than this plan.',
     checkout: {
       description__paymentSuccessful: 'Your payment was successful.',
       description__subscriptionSuccessful: 'Your new subscription is all set.',
diff --git a/packages/shared/src/error.ts b/packages/shared/src/error.ts
@@ -167,6 +167,7 @@ export function parseError(error: ClerkAPIErrorJSON): ClerkAPIError {
       identifiers: error?.meta?.identifiers,
       zxcvbn: error?.meta?.zxcvbn,
       plan: error?.meta?.plan,
+      isPlanUpgradePossible: error?.meta?.is_plan_upgrade_possible,
     },
   };
 }
@@ -188,6 +189,7 @@ export function errorToJSON(error: ClerkAPIError | null): ClerkAPIErrorJSON {
       identifiers: error?.meta?.identifiers,
       zxcvbn: error?.meta?.zxcvbn,
       plan: error?.meta?.plan,
+      is_plan_upgrade_possible: error?.meta?.isPlanUpgradePossible,
     },
   };
 }
diff --git a/packages/types/src/api.ts b/packages/types/src/api.ts
@@ -36,6 +36,7 @@ export interface ClerkAPIError {
       id: string;
       name: string;
     };
+    isPlanUpgradePossible?: boolean;
   };
 }
 
diff --git a/packages/types/src/json.ts b/packages/types/src/json.ts
@@ -358,6 +358,7 @@ export interface ClerkAPIErrorJSON {
       id: string;
       name: string;
     };
+    is_plan_upgrade_possible?: boolean;
   };
 }
 
diff --git a/packages/types/src/localization.ts b/packages/types/src/localization.ts
@@ -214,6 +214,7 @@ export type __internal_LocalizationResource = {
     monthly: LocalizationValue;
     annually: LocalizationValue;
     cannotSubscribeMonthly: LocalizationValue;
+    cannotSubscribeUnrecoverable: LocalizationValue;
     pricingTable: {
       billingCycle: LocalizationValue;
       included: LocalizationValue;

Original file line number	Diff line number	Diff line change
`@@ -36,6 +36,7 @@ export interface ClerkAPIError {`
`36`	`36`	`id: string;`
`37`	`37`	`name: string;`
`38`	`38`	`};`
	`39`	`+ isPlanUpgradePossible?: boolean;`
`39`	`40`	`};`
`40`	`41`	`}`
`41`	`42`
Original file line number	Diff line number	Diff line change
`@@ -358,6 +358,7 @@ export interface ClerkAPIErrorJSON {`
`358`	`358`	`id: string;`
`359`	`359`	`name: string;`
`360`	`360`	`};`
	`361`	`+ is_plan_upgrade_possible?: boolean;`
`361`	`362`	`};`
`362`	`363`	`}`
`363`	`364`