Stripe：如何设置订阅计费周期结束后自动切换不同方案

要实现用户切换订阅后，新方案在当前计费周期结束时自动生效的需求，核心是利用Stripe订阅的延期变更机制，通过API指定变更生效时间为当前周期的结束节点，具体操作如下：

• 获取当前订阅信息
  调用Stripe的订阅查询API，获取用户当前订阅的current_period_end时间（计费周期结束的时间戳），以及订阅项的ID：

  const stripe = require('stripe')('你的Secret Key');
  const subscription = await stripe.subscriptions.retrieve('用户的Subscription ID');
  const currentPeriodEnd = subscription.current_period_end;
  const existingSubscriptionItemId = subscription.items.data[0].id;
  

• 更新订阅并设置延期生效
  调用订阅更新API，指定新的订阅价格ID，同时配置三个关键参数确保延期生效：

  • effective_date: 设置为current_period_end，让新方案在当前周期结束时自动启用
  • proration_behavior: 'none': 禁止生成按比例的费用调整单，避免用户被提前收取新方案费用
  • payment_behavior: 'default_incomplete': 确保Stripe不会立即尝试扣费，仅在新方案生效时发起账单请求

  示例代码：

  const updatedSubscription = await stripe.subscriptions.update(
    '用户的Subscription ID',
    {
      items: [{
        id: existingSubscriptionItemId,
        price: '新方案的Price ID', // 替换为月付/年付方案对应的Price ID
      }],
      effective_date: currentPeriodEnd,
      proration_behavior: 'none',
      payment_behavior: 'default_incomplete',
    }
  );
  

• 处理Webhook同步状态
  为了同步自身系统的用户订阅数据，需要监听Stripe的Webhook事件：

  • customer.subscription.updated: 当订阅的待处理变更被确认，或新方案正式生效时触发
  • invoice.paid: 新方案生效后第一张账单支付成功时触发，此时可更新用户系统内的订阅状态

• 处理多次切换场景
  如果用户在当前计费周期内多次切换方案，Stripe会自动覆盖之前的待处理变更，最终以最后一次提交的方案为准，无需额外开发逻辑

验证方式 #

在Stripe Dashboard的订阅详情页面，会显示「待处理更新」模块，清晰展示新方案的生效时间和具体内容，便于核对配置是否正确。

内容的提问来源于stack exchange，提问作者Pankaj Shah