How to Implement Subscription Changes

Product1:
├── Price: $10/month
└── Price: $100/year
 
Product2:
├── Price: $20/month
└── Price: $200/year
 
Product3:
├── Price: $50/month
└── Price: $500/year

case 'customer.subscription.updated':
  const subscription = event.data.object as Stripe.Subscription;
  const previousAttributes = (event as any).data?.previous_attributes;
 
  const currentPriceId = subscription.items.data[0]?.price.id;
  const previousItems = previousAttributes.items as Stripe.ApiList<Stripe.SubscriptionItem>;
  const previousPriceId = previousItems?.data?.[0]?.price?.id;
 
  if (!currentPriceId || !previousPriceId || currentPriceId === previousPriceId) {
    return defaultResult;
  }
 
  // Then compare the two plans by obtaining them through currentPriceId and previousPriceId, and determine upgrade or downgrade

    if (planId && userId && subscription) {
      // --- [custom] Upgrade ---
      const orderId = insertedOrder.id;
      try {
        await upgradeSubscriptionCredits(userId, planId, orderId, subscription);
      } catch (error) {
        console.error(`CRITICAL: Failed to upgrade subscription credits for user ${userId}, order ${orderId}:`, error);
        await sendCreditUpgradeFailedEmail({ userId, orderId, planId, error });
        throw error;
      }
      // --- End: [custom] Upgrade ---
    }

    if (planId && userId && subscription) {
      // --- [custom] Upgrade ---
      const orderId = insertedOrder.id;
      try {
        // Check if this is a subscription change (upgrade/downgrade) invoice
        const isSubscriptionUpdate = invoice.billing_reason === 'subscription_update' && invoice.lines.data.length === 2;
 
        if (isSubscriptionUpdate) {
          // Get price_id before and after the change
          const currentPriceId = invoice.lines.data[0].pricing.price_details.price
          const previousPriceId = invoice.lines.data[1].pricing.price_details.price
          if (currentPriceId && previousPriceId) {
            // Get pricing information and changeType before and after the change
            const changeResult = await detectSubscriptionChange(currentPriceId, previousPriceId);
            if (changeResult.changeType !== 'none') {
              // Handle subscription change,
              // Due to the complexity of change scenarios, the boilerplate cannot cover all scenarios, so only the entry point and handling suggestions are provided
              // The entry method handleSubscriptionChange is also in the `app/api/stripe/webhook/subscription-change.ts` file
              await handleSubscriptionChange(subscription, changeResult);
              return;
            }
          }
        } else {
          // Not a subscription change, no change
          await upgradeSubscriptionCredits(userId, planId, orderId, subscription);
        }
      } catch (error) {
        console.error(`CRITICAL: Failed to upgrade subscription credits for user ${userId}, order ${orderId}:`, error);
        await sendCreditUpgradeFailedEmail({ userId, orderId, planId, error });
        throw error;
      }
      // --- End: [custom] Upgrade ---
    }

// import ...
 
/**
 * Subscription change type details
 * 订阅变更类型详情
 * サブスクリプション変更タイプの詳細
 */
export type SubscriptionChangeType =
  | 'monthly_to_monthly_upgrade'
  | 'monthly_to_monthly_downgrade'
  | 'yearly_to_yearly_upgrade'
  | 'yearly_to_yearly_downgrade'
  | 'monthly_to_yearly_change'
  | 'yearly_to_monthly_change'
  | 'none'; // no change
 
/**
 * Subscription change detection result
 * 订阅变更检测结果
 * サブスクリプション変更検出結果
 */
export interface SubscriptionChangeResult {
  changeType: SubscriptionChangeType;
  previousPriceId?: string;
  currentPriceId?: string;
  previousPlanId?: string;
  currentPlanId?: string;
  previousInterval?: string;
  currentInterval?: string;
  previousPrice?: string;
  currentPrice?: string;
}
 
const getChangeType = (prevInterval: string, currInterval: string, prevAmount: number, currAmount: number) => {
  if (prevInterval !== currInterval) {
    return `${prevInterval}_to_${currInterval}_change`
  }
 
  if (prevAmount === currAmount) return 'none';
 
  const direction = currAmount > prevAmount ? 'upgrade' : 'downgrade';
  return `${currInterval}_to_${currInterval}_${direction}`
};
 
/**
 * Detects if a subscription update is an upgrade, downgrade, or interval change
 * 检测订阅更新是升级、降级还是周期变更
 * サブスクリプションの更新がアップグレード、ダウングレード、または期間変更かを検出
 */
export async function detectSubscriptionChange(
  currentPriceId: string,
  previousPriceId: string
) {
  const defaultResult: SubscriptionChangeResult = {
    changeType: 'none',
  };
 
  if (!currentPriceId || !previousPriceId) {
    return defaultResult;
  }
 
  // Fetch plan information from database to compare
  const [currentPlanResults, previousPlanResults] = await Promise.all([
    db
      .select({
        id: pricingPlansSchema.id,
        price: pricingPlansSchema.price,
        recurringInterval: pricingPlansSchema.recurringInterval,
        benefitsJsonb: pricingPlansSchema.benefitsJsonb,
      })
      .from(pricingPlansSchema)
      .where(eq(pricingPlansSchema.stripePriceId, currentPriceId))
      .limit(1),
    db
      .select({
        id: pricingPlansSchema.id,
        price: pricingPlansSchema.price,
        recurringInterval: pricingPlansSchema.recurringInterval,
        benefitsJsonb: pricingPlansSchema.benefitsJsonb,
      })
      .from(pricingPlansSchema)
      .where(eq(pricingPlansSchema.stripePriceId, previousPriceId))
      .limit(1),
  ]);
 
  const currentPlan = currentPlanResults[0];
  const previousPlan = previousPlanResults[0];
 
  if (!currentPlan || !previousPlan) {
    console.warn(`Could not find plan data for price comparison. Current: ${currentPriceId}, Previous: ${previousPriceId}`);
    return defaultResult;
  }
 
  const currentInterval = currentPlan.recurringInterval?.toLowerCase();
  const previousInterval = previousPlan.recurringInterval?.toLowerCase();
  const currentAmount = parseFloat(currentPlan.price || '0');
  const previousAmount = parseFloat(previousPlan.price || '0');
 
  // Determine change type based on interval and price
  const changeType = getChangeType(previousInterval as string, currentInterval as string, previousAmount, currentAmount);
 
  return {
    changeType: changeType || 'none',
    previousPriceId,
    currentPriceId,
    previousPlanId: previousPlan.id,
    currentPlanId: currentPlan.id,
    previousInterval: previousInterval || undefined,
    currentInterval: currentInterval || undefined,
    previousPrice: previousPlan.price || undefined,
    currentPrice: currentPlan.price || undefined,
  };
}
 
/**
 * Main router function for handling subscription changes
 * 订阅变更的主路由函数
 * サブスクリプション変更のメインルーター関数
 */
export async function handleSubscriptionChange(
  subscription: Stripe.Subscription,
  changeResult: SubscriptionChangeResult
) {
  // ...
}