Stripe Subscription Schedules异常：单次更新计划需两次周期生效

需求 #

配置Subscription Schedules，让订阅执行一次价格切换后，直接转为新价格的常规订阅，不再保留后续调度。

当前背景 #

已有活跃订阅，已调度在下一计费周期切换到新的Plan/Price，基础切换功能正常。

操作步骤 #

1. 从当前订阅创建Subscription Schedule：

const scheduledSubscription = await this.stripe.subscriptionSchedules.create({
  "from_subscription": stripeSubscriptionId,
});

2. 更新Schedule，设置第一阶段为当前订阅到周期结束，之后切换至新Price：

// Update the schedule with the new phase
const downgradedSubscription = await this.stripe.subscriptionSchedules.update(scheduledSubscription.id, {
  "phases": [
    {
      "items": [
        {
          "price": scheduledSubscription.phases[0].items[0].price,
          "quantity": scheduledSubscription.phases[0].items[0].quantity,
        },
      ],
      "start_date": scheduledSubscription.phases[0].start_date,
      "end_date": scheduledSubscription.phases[0].end_date,
    },
    {
      "items": [
        {
          "price": newPriceId,
          "quantity": 1,
        },
      ],
    },
  ],
});

问题详情 #

1. 执行代码前的默认状态：活跃订阅，无调度，下一计费周期无变更
2. 调用subscriptionSchedules.update后的状态：订阅已调度，下一周期将切换到新价格
3. 推进时钟一个月后的状态：订阅已切换到新价格，但仍保留调度，下一周期将继续按新价格计费
4. 期望目标状态：活跃订阅，无调度，新价格持续生效（实际需再经过一个周期才达到）

解决方案 #

问题根源是未指定end_behavior参数，默认end_behavior: 'renew'会让最后一个阶段重复执行，导致订阅一直处于调度状态。需在更新Schedule时添加end_behavior: 'release'，让调度在最后一个阶段结束后自动释放订阅为常规状态。

修改后的代码：

const downgradedSubscription = await this.stripe.subscriptionSchedules.update(scheduledSubscription.id, {
  "phases": [
    {
      "items": [
        {
          "price": scheduledSubscription.phases[0].items[0].price,
          "quantity": scheduledSubscription.phases[0].items[0].quantity,
        },
      ],
      "start_date": scheduledSubscription.phases[0].start_date,
      "end_date": scheduledSubscription.phases[0].end_date,
    },
    {
      "items": [
        {
          "price": newPriceId,
          "quantity": 1,
        },
      ],
    },
  ],
  "end_behavior": "release" // 调度结束后释放为常规订阅
});

说明 #

• end_behavior: 'release'：Subscription Schedule在最后一个阶段结束后自动释放，订阅转为无调度的常规状态，新价格持续生效
• 第二个阶段无需设置end_date，会自动沿用订阅的计费周期，执行一次后触发释放

测试验证：

1. 更新调度后，订阅状态显示下一周期切换新价格，调度结束后将释放
2. 推进时钟一个月，订阅切换到新价格，同时Schedule被释放，订阅变为常规状态，无后续调度，符合目标

内容的提问来源于stack exchange，提问作者Jan Bouchner