如何在Stripe中实现先付款后升级的订阅计划变更流程

在Stripe的订阅体系中，默认的订阅升级逻辑会基于剩余周期时长按比例计算补差价，但部分业务场景要求用户必须先支付全额新订阅费用，完成付款后再切换到更高等级的订阅计划，这就需要开发者自定义订阅变更的处理流程，绕过默认的比例计费逻辑。

前期准备工作

在开始实现功能前，需要先完成以下基础配置：

• 在Stripe后台创建至少两个不同价格的订阅计划，记录下对应计划的price_id
• 确保项目中已经集成Stripe官方SDK，本文示例使用Node.js的Stripe SDK
• 配置好Stripe的API密钥，区分测试环境和生产环境

核心实现流程

第一步：创建新订阅的付款会话

当用户发起升级请求时，首先不要直接修改原有订阅，而是为用户创建一个新订阅的付款会话，让用户先完成新订阅的全额付款。这里需要使用stripe.checkout.sessions.create接口，设置mode为subscription，指定新的price_id，同时需要关联用户的Stripe客户ID。

const stripe = require('stripe')('sk_test_你的测试密钥');
const express = require('express');
const app = express();

// 创建升级付款会话的接口
app.post('/create-upgrade-session', async (req, res) => {
  try {
    const { customer_id, new_price_id, old_subscription_id } = req.body;
    // 创建Checkout会话，用户付款后会跳转到success_url
    const session = await stripe.checkout.sessions.create({
      customer: customer_id,
      payment_method_types: ['card'],
      line_items: [
        {
          price: new_price_id,
          quantity: 1,
        },
      ],
      mode: 'subscription',
      // 将旧订阅ID存入元数据，付款成功回调时使用
      metadata: {
        old_subscription_id: old_subscription_id,
        is_upgrade: 'true'
      },
      success_url: 'https://你的域名/upgrade-success?session_id={CHECKOUT_SESSION_ID}',
      cancel_url: 'https://你的域名/upgrade-cancel',
    });
    res.json({ session_id: session.id });
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

第二步：处理付款成功回调

用户完成付款后，Stripe会发送checkout.session.completed事件到配置的Webhook地址，我们需要在Webhook处理逻辑中，先验证事件真实性，然后判断是否为升级相关的会话，如果是则取消旧的订阅，同时将新订阅的状态同步到自己的业务系统。

// Webhook处理接口
app.post('/stripe-webhook', express.raw({type: 'application/json'}), async (req, res) => {
  const sig = req.headers['stripe-signature'];
  const endpointSecret = "whsec_你的Webhook密钥";
  let event;
  try {
    event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret);
  } catch (err) {
    return res.status(400).send(`Webhook签名验证失败: ${err.message}`);
  }

  // 处理Checkout会话完成事件
  if (event.type === 'checkout.session.completed') {
    const session = event.data.object;
    // 判断是否为升级场景
    if (session.metadata.is_upgrade === 'true') {
      const oldSubscriptionId = session.metadata.old_subscription_id;
      const newSubscriptionId = session.subscription;
      // 取消旧的订阅，设置取消时间为当前周期结束，避免重复扣费
      await stripe.subscriptions.update(oldSubscriptionId, {
        cancel_at_period_end: true
      });
      // 这里可以将新订阅ID、用户ID的关联关系同步到自己的数据库
      console.log(`用户升级成功，旧订阅${oldSubscriptionId}将在周期结束后取消，新订阅${newSubscriptionId}已生效`);
    }
  }
  res.json({ received: true });
});

第三步：处理订阅状态同步

为了避免旧订阅在当前周期结束前仍然生效，我们还可以在用户付款成功后，主动调用接口查询新订阅的状态，确认新订阅已经激活后，再给用户开放对应等级的权限，同时标记旧订阅为待取消状态。

// 验证付款结果并同步权限的接口
app.get('/verify-upgrade', async (req, res) => {
  try {
    const { session_id } = req.query;
    const session = await stripe.checkout.sessions.retrieve(session_id);
    if (session.payment_status === 'paid') {
      const newSubscription = await stripe.subscriptions.retrieve(session.subscription);
      if (newSubscription.status === 'active') {
        // 这里更新业务系统的用户权限，开放新订阅对应的功能
        return res.json({ success: true, message: '升级成功，权限已更新' });
      }
    }
    res.json({ success: false, message: '付款未完成或订阅未生效' });
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

注意事项

• 取消旧订阅时建议使用cancel_at_period_end: true，而不是直接调用cancel接口，这样用户可以在当前已付费的周期内继续使用原有服务，提升用户体验
• Webhook的处理必须做好幂等性设计，避免同一个事件被重复处理导致旧订阅被多次取消
• 测试阶段建议使用Stripe的测试卡完成付款流程，验证整个链路是否正常
• 如果用户付款后主动取消新订阅，需要做好对应的回滚逻辑，恢复用户的旧订阅状态

常见问题

为什么不直接修改原有订阅的price？

直接调用stripe.subscriptions.update修改items的price，Stripe默认会按比例计算剩余周期的补差价，无法实现先付全额再升级的需求，因此才需要走先创建新订阅付款，再取消旧订阅的流程。

旧订阅的未使用费用如何处理？

如果业务需要退还旧订阅剩余周期的费用，可以在取消旧订阅时调用Stripe的退款接口，按照剩余周期的比例计算退款金额，退款金额可以通过stripe.invoices.retrieveUpcoming接口提前计算。

Stripe订阅计划变更先付款后升级支付流程subscription_update修改时间：2026-07-23 12:12:34