@better-auth/stripe 1.4.16 → 1.4.18

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@better-auth/stripe",
   "author": "Bereket Engida",
-  "version": "1.4.16",
+  "version": "1.4.18",
   "type": "module",
   "main": "dist/index.mjs",
   "types": "dist/index.d.mts",
@@ -46,19 +46,19 @@
   },
   "dependencies": {
     "defu": "^6.1.4",
-    "zod": "^4.1.12"
+    "zod": "^4.3.5"
   },
   "peerDependencies": {
     "stripe": "^18 || ^19 || ^20",
-    "@better-auth/core": "1.4.16",
-    "better-auth": "1.4.16"
+    "@better-auth/core": "1.4.18",
+    "better-auth": "1.4.18"
   },
   "devDependencies": {
     "better-call": "1.1.8",
     "stripe": "^20.0.0",
     "tsdown": "^0.17.2",
-    "@better-auth/core": "1.4.16",
-    "better-auth": "1.4.16"
+    "@better-auth/core": "1.4.18",
+    "better-auth": "1.4.18"
   },
   "scripts": {
     "test": "vitest",

package/src/client.ts

@@ -1,4 +1,4 @@
-import type { BetterAuthClientPlugin } from "better-auth";
+import type { BetterAuthClientPlugin } from "better-auth/client";
 import type { stripe } from "./index";
 
 export const stripeClient = <

package/src/hooks.ts

@@ -2,6 +2,7 @@ import type { GenericEndpointContext } from "@better-auth/core";
 import type { User } from "@better-auth/core/db";
 import type { Organization } from "better-auth/plugins/organization";
 import type Stripe from "stripe";
+import { subscriptionMetadata } from "./metadata";
 import type { CustomerType, StripeOptions, Subscription } from "./types";
 import {
 	getPlanByPriceInfo,
@@ -66,10 +67,10 @@ export async function onCheckoutSessionCompleted(
 			priceLookupKey,
 		);
 		if (plan) {
+			const checkoutMeta = subscriptionMetadata.get(checkoutSession?.metadata);
 			const referenceId =
-				checkoutSession?.client_reference_id ||
-				checkoutSession?.metadata?.referenceId;
-			const subscriptionId = checkoutSession?.metadata?.subscriptionId;
+				checkoutSession?.client_reference_id || checkoutMeta.referenceId;
+			const { subscriptionId } = checkoutMeta;
 			const seats = subscriptionItem.quantity;
 			if (referenceId && subscriptionId) {
 				const trial =
@@ -162,7 +163,9 @@ export async function onSubscriptionCreated(
 		}
 
 		// Check if subscription already exists in database
-		const subscriptionId = subscriptionCreated.metadata?.subscriptionId;
+		const { subscriptionId } = subscriptionMetadata.get(
+			subscriptionCreated.metadata,
+		);
 		const existingSubscription =
 			await ctx.context.adapter.findOne<Subscription>({
 				model: "subscription",
@@ -275,7 +278,9 @@ export async function onSubscriptionUpdated(
 		const priceLookupKey = subscriptionItem.price.lookup_key;
 		const plan = await getPlanByPriceInfo(options, priceId, priceLookupKey);
 
-		const subscriptionId = subscriptionUpdated.metadata?.subscriptionId;
+		const { subscriptionId } = subscriptionMetadata.get(
+			subscriptionUpdated.metadata,
+		);
 		const customerId = subscriptionUpdated.customer?.toString();
 		let subscription = await ctx.context.adapter.findOne<Subscription>({
 			model: "subscription",

package/src/index.ts

@@ -8,6 +8,7 @@ import type {
 import { defu } from "defu";
 import type Stripe from "stripe";
 import { STRIPE_ERROR_CODES } from "./error-codes";
+import { customerMetadata } from "./metadata";
 import {
 	cancelSubscription,
 	cancelSubscriptionCallback,
@@ -178,7 +179,7 @@ export const stripe = <O extends StripeOptions>(options: O) => {
 									try {
 										// Check if user customer already exists in Stripe by email
 										const existingCustomers = await client.customers.search({
-											query: `email:"${escapeStripeSearchValue(user.email)}" AND -metadata["customerType"]:"organization"`,
+											query: `email:"${escapeStripeSearchValue(user.email)}" AND -metadata["${customerMetadata.keys.customerType}"]:"organization"`,
 											limit: 1,
 										});
 
@@ -215,14 +216,17 @@ export const stripe = <O extends StripeOptions>(options: O) => {
 											);
 										}
 
-										const params: Stripe.CustomerCreateParams = defu(
+										const params = defu(
 											{
 												email: user.email,
 												name: user.name,
-												metadata: {
-													userId: user.id,
-													customerType: "user",
-												},
+												metadata: customerMetadata.set(
+													{
+														userId: user.id,
+														customerType: "user",
+													},
+													extraCreateParams?.metadata,
+												),
 											},
 											extraCreateParams,
 										);

package/src/metadata.ts

@@ -0,0 +1,94 @@
+import { defu } from "defu";
+import type Stripe from "stripe";
+
+/**
+ * Internal metadata fields for Stripe Customer.
+ */
+type CustomerInternalMetadata =
+	| { customerType: "user"; userId: string }
+	| { customerType: "organization"; organizationId: string };
+
+/**
+ * Internal metadata fields for Stripe Subscription/Checkout.
+ */
+type SubscriptionInternalMetadata = {
+	userId: string;
+	subscriptionId: string;
+	referenceId: string;
+};
+
+/**
+ * Customer metadata - set internal fields and extract typed fields.
+ */
+export const customerMetadata = {
+	/**
+	 * Internal metadata keys for type-safe access.
+	 */
+	keys: {
+		userId: "userId",
+		organizationId: "organizationId",
+		customerType: "customerType",
+	} as const,
+
+	/**
+	 * Create metadata with internal fields that cannot be overridden by user metadata.
+	 * Uses `defu` which prioritizes the first argument.
+	 */
+	set(
+		internalFields: CustomerInternalMetadata,
+		...userMetadata: (Stripe.Emptyable<Stripe.MetadataParam> | undefined)[]
+	): Stripe.MetadataParam {
+		return defu(internalFields, ...userMetadata.filter(Boolean));
+	},
+
+	/**
+	 * Extract internal fields from Stripe metadata.
+	 * Provides type-safe access to internal metadata keys.
+	 */
+	get(metadata: Stripe.Metadata | null | undefined) {
+		return {
+			userId: metadata?.userId,
+			organizationId: metadata?.organizationId,
+			customerType: metadata?.customerType as
+				| CustomerInternalMetadata["customerType"]
+				| undefined,
+		};
+	},
+};
+
+/**
+ * Subscription/Checkout metadata - set internal fields and extract typed fields.
+ */
+export const subscriptionMetadata = {
+	/**
+	 * Internal metadata keys for type-safe access.
+	 */
+	keys: {
+		userId: "userId",
+		subscriptionId: "subscriptionId",
+		referenceId: "referenceId",
+	} as const,
+
+	/**
+	 * Create metadata with internal fields that cannot be overridden by user metadata.
+	 * Uses `defu` which prioritizes the first argument.
+	 */
+	set(
+		internalFields: SubscriptionInternalMetadata,
+		...userMetadata: (Stripe.Emptyable<Stripe.MetadataParam> | undefined)[]
+	): Stripe.MetadataParam {
+		return defu(internalFields, ...userMetadata.filter(Boolean));
+	},
+
+	/**
+	 * Extract internal fields from Stripe metadata.
+	 * Provides type-safe access to internal metadata keys.
+	 */
+	get(metadata: Stripe.Metadata | null | undefined) {
+		return {
+			userId: metadata?.userId,
+			subscriptionId: metadata?.subscriptionId,
+			referenceId: metadata?.referenceId,
+		};
+	},
+};

package/src/routes.ts

@@ -14,6 +14,7 @@ import {
 	onSubscriptionDeleted,
 	onSubscriptionUpdated,
 } from "./hooks";
+import { customerMetadata, subscriptionMetadata } from "./metadata";
 import { referenceMiddleware, stripeSessionMiddleware } from "./middleware";
 import type {
 	CustomerType,
@@ -269,8 +270,9 @@ export const upgradeSubscription = (options: StripeOptions) => {
 				});
 			}
 
-			// Find existing subscription by Stripe ID or reference ID
-			let subscriptionToUpdate = ctx.body.subscriptionId
+			// If subscriptionId is provided, find that specific subscription.
+			// Otherwise, active subscription will be resolved by referenceId later.
+			const subscriptionToUpdate = ctx.body.subscriptionId
 				? await ctx.context.adapter.findOne<Subscription>({
 						model: "subscription",
 						where: [
@@ -280,26 +282,17 @@ export const upgradeSubscription = (options: StripeOptions) => {
 							},
 						],
 					})
-				: referenceId
-					? await ctx.context.adapter.findOne<Subscription>({
-							model: "subscription",
-							where: [
-								{
-									field: "referenceId",
-									value: referenceId,
-								},
-							],
-						})
-					: null;
-
+				: null;
+			if (ctx.body.subscriptionId && !subscriptionToUpdate) {
+				throw new APIError("BAD_REQUEST", {
+					message: STRIPE_ERROR_CODES.SUBSCRIPTION_NOT_FOUND,
+				});
+			}
 			if (
 				ctx.body.subscriptionId &&
 				subscriptionToUpdate &&
 				subscriptionToUpdate.referenceId !== referenceId
 			) {
-				subscriptionToUpdate = null;
-			}
-			if (ctx.body.subscriptionId && !subscriptionToUpdate) {
 				throw new APIError("BAD_REQUEST", {
 					message: STRIPE_ERROR_CODES.SUBSCRIPTION_NOT_FOUND,
 				});
@@ -334,7 +327,7 @@ export const upgradeSubscription = (options: StripeOptions) => {
 						try {
 							// First, search for existing organization customer by organizationId
 							const existingOrgCustomers = await client.customers.search({
-								query: `metadata["organizationId"]:"${org.id}"`,
+								query: `metadata["${customerMetadata.keys.organizationId}"]:"${org.id}"`,
 								limit: 1,
 							});
 
@@ -354,15 +347,17 @@ export const upgradeSubscription = (options: StripeOptions) => {
 
 								// Create Stripe customer for organization
 								// Email can be set via getCustomerCreateParams or updated in billing portal
-								// Use defu to ensure internal metadata fields are preserved
-								const customerParams: StripeType.CustomerCreateParams = defu(
+								// Use defu to merge params (first argument takes priority)
+								const customerParams = defu(
 									{
 										name: org.name,
-										metadata: {
-											...ctx.body.metadata,
-											organizationId: org.id,
-											customerType: "organization",
-										},
+										metadata: customerMetadata.set(
+											{
+												organizationId: org.id,
+												customerType: "organization",
+											},
+											ctx.body.metadata,
+										),
 									},
 									extraCreateParams,
 								);
@@ -411,7 +406,7 @@ export const upgradeSubscription = (options: StripeOptions) => {
 					try {
 						// Try to find existing user Stripe customer by email
 						const existingCustomers = await client.customers.search({
-							query: `email:"${escapeStripeSearchValue(user.email)}" AND -metadata["customerType"]:"organization"`,
+							query: `email:"${escapeStripeSearchValue(user.email)}" AND -metadata["${customerMetadata.keys.customerType}"]:"organization"`,
 							limit: 1,
 						});
 
@@ -421,11 +416,13 @@ export const upgradeSubscription = (options: StripeOptions) => {
 							stripeCustomer = await client.customers.create({
 								email: user.email,
 								name: user.name,
-								metadata: {
-									...ctx.body.metadata,
-									userId: user.id,
-									customerType: "user",
-								},
+								metadata: customerMetadata.set(
+									{
+										userId: user.id,
+										customerType: "user",
+									},
+									ctx.body.metadata,
+								),
 							});
 						}
 
@@ -493,17 +490,47 @@ export const upgradeSubscription = (options: StripeOptions) => {
 				return false;
 			});
 
+			// Get the current price ID from the active Stripe subscription
+			const stripeSubscriptionPriceId =
+				activeSubscription?.items.data[0]?.price.id;
+
 			// Also find any incomplete subscription that we can reuse
 			const incompleteSubscription = subscriptions.find(
 				(sub) => sub.status === "incomplete",
 			);
 
-			if (
-				activeOrTrialingSubscription &&
-				activeOrTrialingSubscription.status === "active" &&
-				activeOrTrialingSubscription.plan === ctx.body.plan &&
-				activeOrTrialingSubscription.seats === (ctx.body.seats || 1)
-			) {
+			const priceId = ctx.body.annual
+				? plan.annualDiscountPriceId
+				: plan.priceId;
+			const lookupKey = ctx.body.annual
+				? plan.annualDiscountLookupKey
+				: plan.lookupKey;
+			const resolvedPriceId = lookupKey
+				? await resolvePriceIdFromLookupKey(client, lookupKey)
+				: undefined;
+
+			const priceIdToUse = priceId || resolvedPriceId;
+			if (!priceIdToUse) {
+				throw ctx.error("BAD_REQUEST", {
+					message: "Price ID not found for the selected plan",
+				});
+			}
+
+			const isSamePlan = activeOrTrialingSubscription?.plan === ctx.body.plan;
+			const isSameSeats =
+				activeOrTrialingSubscription?.seats === (ctx.body.seats || 1);
+			const isSamePriceId = stripeSubscriptionPriceId === priceIdToUse;
+			const isSubscriptionStillValid =
+				!activeOrTrialingSubscription?.periodEnd ||
+				activeOrTrialingSubscription.periodEnd > new Date();
+
+			const isAlreadySubscribed =
+				activeOrTrialingSubscription?.status === "active" &&
+				isSamePlan &&
+				isSameSeats &&
+				isSamePriceId &&
+				isSubscriptionStillValid;
+			if (isAlreadySubscribed) {
 				throw new APIError("BAD_REQUEST", {
 					message: STRIPE_ERROR_CODES.ALREADY_SUBSCRIBED_PLAN,
 				});
@@ -539,32 +566,6 @@ export const upgradeSubscription = (options: StripeOptions) => {
 					dbSubscription = activeOrTrialingSubscription;
 				}
 
-				// Resolve price ID if using lookup keys
-				let priceIdToUse: string | undefined = undefined;
-				if (ctx.body.annual) {
-					priceIdToUse = plan.annualDiscountPriceId;
-					if (!priceIdToUse && plan.annualDiscountLookupKey) {
-						priceIdToUse = await resolvePriceIdFromLookupKey(
-							client,
-							plan.annualDiscountLookupKey,
-						);
-					}
-				} else {
-					priceIdToUse = plan.priceId;
-					if (!priceIdToUse && plan.lookupKey) {
-						priceIdToUse = await resolvePriceIdFromLookupKey(
-							client,
-							plan.lookupKey,
-						);
-					}
-				}
-
-				if (!priceIdToUse) {
-					throw ctx.error("BAD_REQUEST", {
-						message: "Price ID not found for the selected plan",
-					});
-				}
-
 				const { url } = await client.billingPortal.sessions
 					.create({
 						customer: customerId,
@@ -672,24 +673,6 @@ export const upgradeSubscription = (options: StripeOptions) => {
 					? { trial_period_days: plan.freeTrial.days }
 					: undefined;
 
-			let priceIdToUse: string | undefined = undefined;
-			if (ctx.body.annual) {
-				priceIdToUse = plan.annualDiscountPriceId;
-				if (!priceIdToUse && plan.annualDiscountLookupKey) {
-					priceIdToUse = await resolvePriceIdFromLookupKey(
-						client,
-						plan.annualDiscountLookupKey,
-					);
-				}
-			} else {
-				priceIdToUse = plan.priceId;
-				if (!priceIdToUse && plan.lookupKey) {
-					priceIdToUse = await resolvePriceIdFromLookupKey(
-						client,
-						plan.lookupKey,
-					);
-				}
-			}
 			const checkoutSession = await client.checkout.sessions
 				.create(
 					{
@@ -722,24 +705,29 @@ export const upgradeSubscription = (options: StripeOptions) => {
 						],
 						subscription_data: {
 							...freeTrial,
-							metadata: {
-								...ctx.body.metadata,
-								...params?.params?.subscription_data?.metadata,
-								userId: user.id,
-								subscriptionId: subscription.id,
-								referenceId,
-							},
+							metadata: subscriptionMetadata.set(
+								{
+									userId: user.id,
+									subscriptionId: subscription.id,
+									referenceId,
+								},
+								ctx.body.metadata,
+								params?.params?.subscription_data?.metadata,
+							),
 						},
 						mode: "subscription",
 						client_reference_id: referenceId,
 						...params?.params,
-						metadata: {
-							...ctx.body.metadata,
-							...params?.params?.metadata,
-							userId: user.id,
-							subscriptionId: subscription.id,
-							referenceId,
-						},
+						// metadata should come after spread to protect internal fields
+						metadata: subscriptionMetadata.set(
+							{
+								userId: user.id,
+								subscriptionId: subscription.id,
+								referenceId,
+							},
+							ctx.body.metadata,
+							params?.params?.metadata,
+						),
 					},
 					params?.options,
 				)