如何为Stripe存量订阅客户更新订阅价格？

单个客户切换方案 #

1. Stripe后台手动操作

• 进入目标客户的订阅详情页，点击「Update subscription」
• 在「Pricing」模块选择已创建的新价格
• 选择生效时机：
  • 立即生效：可配置是否按比例收取当前周期剩余时间的差价（在「Proration settings」中调整）
  • 下一个计费周期生效：订阅会在当前周期结束后自动切换到新价格，无额外差价
• 确认设置后完成更新

2. API调用更新（以Node.js为例）

使用subscriptions.update接口替换订阅价格：

const stripe = require('stripe')('你的API密钥');

async function updateSubscriptionPrice(subscriptionId, newPriceId) {
  const subscription = await stripe.subscriptions.retrieve(subscriptionId);
  const subscriptionItemId = subscription.items.data[0].id;

  const updatedSubscription = await stripe.subscriptions.update(
    subscriptionId,
    {
      items: [{
        id: subscriptionItemId,
        price: newPriceId
      }],
      // 可选：控制差价计费逻辑，'none'表示不生成差价账单
      proration_behavior: 'create_prorations',
      // 可选：处理支付失败的策略，'default_incomplete'允许客户后续补付
      payment_behavior: 'default_incomplete'
    }
  );
  return updatedSubscription;
}

注：如果订阅包含多个项目，需遍历subscription.items.data逐一替换对应价格ID

批量处理存量客户方案 #

1. Stripe后台批量操作工具

• 进入「Billing > Subscriptions」页面，通过筛选器选择所有使用旧价格的订阅
• 点击「Bulk actions」→「Update subscriptions」
• 配置新价格、生效时机、差价规则，预览变更后执行批量更新

适合客户量较少（几百级）的场景

2. API批量遍历更新

先筛选出所有使用旧价格的订阅，再逐一更新：

const stripe = require('stripe')('你的API密钥');

async function getOldPriceSubscriptions(oldPriceId) {
  let allSubscriptions = [];
  let hasMore = true;
  let startingAfter = null;

  while (hasMore) {
    const response = await stripe.subscriptions.list({
      price: oldPriceId,
      limit: 100,
      starting_after: startingAfter
    });
    allSubscriptions = [...allSubscriptions, ...response.data];
    hasMore = response.has_more;
    startingAfter = response.data.length ? response.data.at(-1).id : null;
  }
  return allSubscriptions;
}

async function batchUpdateSubscriptions(oldPriceId, newPriceId) {
  const oldSubscriptions = await getOldPriceSubscriptions(oldPriceId);
  
  for (const sub of oldSubscriptions) {
    try {
      await stripe.subscriptions.update(sub.id, {
        items: [{
          id: sub.items.data[0].id,
          price: newPriceId
        }],
        proration_behavior: 'none' // 根据业务需求调整
      });
      console.log(`订阅 ${sub.id} 价格更新成功`);
    } catch (err) {
      console.error(`订阅 ${sub.id} 更新失败: ${err.message}`);
    }
  }
}

注：批量操作需注意Stripe API速率限制，建议添加请求延迟（如每100个请求暂停1秒），避免触发限流

关键注意事项 #

• 客户通知：切换前务必通过邮件/站内信告知客户价格变更的原因、生效时间，避免投诉
• 测试验证：先选取少量测试客户的订阅进行更新，确认账单生成、订阅状态、支付流程正常后再批量操作
• 差价控制：如果选择立即生效，可通过proration_behavior参数控制是否收取差价；若希望在下次计费日自动切换，无需配置差价规则
• 支付失败处理：更新时若客户支付方式失效，订阅可能进入incomplete状态，需提前配置支付重试机制或引导客户更新支付方式

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