From b636bd691c0ecab722ca99bc0fc58b727dd9ffe7 Mon Sep 17 00:00:00 2001
From: Taesu <166604494+bytaesu@users.noreply.github.com>
Date: Sat, 17 Jan 2026 06:14:29 +0900
Subject: [PATCH] feat(stripe): add support for `locale` option to
 upgradeSubscription (#7421)

---
 docs/content/docs/plugins/stripe.mdx | 17 ++++++++++++-----
 packages/stripe/src/routes.ts        | 22 ++++++++++++++++++++++
 2 files changed, 34 insertions(+), 5 deletions(-)

diff --git a/docs/content/docs/plugins/stripe.mdx b/docs/content/docs/plugins/stripe.mdx
index e557c657ff..0b92e43839 100644
--- a/docs/content/docs/plugins/stripe.mdx
+++ b/docs/content/docs/plugins/stripe.mdx
@@ -215,11 +215,11 @@ To create a subscription, use the `subscription.upgrade` method:
 ```ts
 type upgradeSubscription = {
     /**
-     * The name of the plan to upgrade to. 
+     * The name of the plan to upgrade to.
      */
     plan: string = "pro"
     /**
-     * Whether to upgrade to an annual plan. 
+     * Whether to upgrade to an annual plan.
      */
     annual?: boolean = true
     /**
@@ -242,6 +242,11 @@ type upgradeSubscription = {
      * Number of seats to upgrade to (if applicable).
      */
     seats?: number = 1
+    /**
+     * The IETF language tag of the locale Checkout is displayed in.
+     * If not provided or set to `auto`, the browser's locale is used.
+     */
+    locale?: string
     /**
      * The URL to which Stripe should send customers when payment or setup is complete.
      */
@@ -255,7 +260,7 @@ type upgradeSubscription = {
      */
     returnUrl?: string
     /**
-     * Disable redirect after successful subscription. 
+     * Disable redirect after successful subscription.
      */
     disableRedirect: boolean = false
 }
@@ -271,7 +276,8 @@ await authClient.subscription.upgrade({
     cancelUrl: "/pricing",
     annual: true, // Optional: upgrade to an annual plan
     referenceId: "org_123", // Optional: defaults based on customerType
-    seats: 5 // Optional: for team plans
+    seats: 5, // Optional: for team plans
+    locale: "en" // Optional: display checkout in English
 });
 ```
 
@@ -466,7 +472,8 @@ To create a [Stripe billing portal session](https://docs.stripe.com/api/customer
 ```ts
 type createBillingPortal = {
     /**
-    * The IETF language tag of the locale customer portal is displayed in. If blank or auto, browser's locale is used.
+    * The IETF language tag of the locale Customer Portal is displayed in.
+    * If not provided or set to `auto`, the browser's locale is used.
     */
     locale?: string
     /**
diff --git a/packages/stripe/src/routes.ts b/packages/stripe/src/routes.ts
index f686586ed6..ac7d018ea5 100644
--- a/packages/stripe/src/routes.ts
+++ b/packages/stripe/src/routes.ts
@@ -158,6 +158,19 @@ const upgradeSubscriptionBodySchema = z.object({
 			description: "Number of seats to upgrade to (if applicable). Eg: 1",
 		})
 		.optional(),
+	/**
+	 * The IETF language tag of the locale Checkout is displayed in.
+	 * If not provided or set to `auto`, the browser's locale is used.
+	 */
+	locale: z
+		.custom<StripeType.Checkout.Session.Locale>((localization) => {
+			return typeof localization === "string";
+		})
+		.meta({
+			description:
+				"The locale to display Checkout in. Eg: 'en', 'ko'. If not provided or set to `auto`, the browser's locale is used.",
+		})
+		.optional(),
 	/**
 	 * The URL to which Stripe should send customers when payment or setup is complete.
 	 */
@@ -691,6 +704,7 @@ export const upgradeSubscription = (options: StripeOptions) => {
 							: {
 									customer_email: user.email,
 								}),
+						locale: ctx.body.locale,
 						success_url: getUrl(
 							ctx,
 							`${
@@ -1412,10 +1426,18 @@ export const subscriptionSuccess = (options: StripeOptions) => {
 };
 
 const createBillingPortalBodySchema = z.object({
+	/**
+	 * The IETF language tag of the locale Customer Portal is displayed in.
+	 * If not provided or set to `auto`, the browser's locale is used.
+	 */
 	locale: z
 		.custom<StripeType.Checkout.Session.Locale>((localization) => {
 			return typeof localization === "string";
 		})
+		.meta({
+			description:
+				"The IETF language tag of the locale Customer Portal is displayed in. Eg: 'en', 'ko'. If not provided or set to `auto`, the browser's locale is used.",
+		})
 		.optional(),
 	referenceId: z.string().optional(),
 	/**