Stripe升级/降级订阅时如何正确获取待支付的预估发票？

嘿，这个问题我之前也碰到过，来给你捋清楚怎么解决！

错误原因解析 #

你遇到的Currency and interval fields must match across all plans on this subscription错误，核心原因是Stripe要求同一个订阅下的所有定价方案（Plan/Price）必须拥有完全一致的计费周期（interval）和货币（currency）。你当前的订阅是月度，目标套餐是年度，两者计费周期不匹配，直接修改原订阅的subscription_items自然会触发这个限制。

正确实现方案 #

要跨周期升级/降级并准确预估发票金额（同时考虑优惠券、客户余额/信用额度），你需要模拟创建一个全新的订阅来计算，而不是修改现有订阅。具体代码如下：

// 预估跨周期订阅变更的发票金额
$upcomingInvoice = \Stripe\Invoice::upcoming([
    "customer" => $user->stripe_id,
    // 指定目标订阅的定价（建议用Stripe推荐的Price ID，替代旧的Plan ID）
    "subscription_items" => [
        [
            "price" => "price_XXXXXXXXXXX", // 你的年度套餐Price ID
            "quantity" => 1
        ]
    ],
    // 配置 prorate 规则：按当前订阅剩余周期计算费用调整
    "subscription_proration_behavior" => "create_prorations",
    // 设置立即生效，触发 prorate 计算（如果希望等到当前周期结束再切换，可改为"unchanged"）
    "subscription_billing_cycle_anchor" => "now",
    // 可选：如果需要手动指定优惠券（比如原订阅专属优惠券），否则Stripe会自动应用客户账户的默认优惠券
    // "coupon" => $user->stripe_coupon_id,
]);

// 提取预估金额（已扣除余额、应用优惠券后的最终金额）
$estimatedAmount = $upcomingInvoice->amount_due;

关键细节说明 #

• 客户余额自动抵扣：Stripe的upcoming接口会自动将客户的现有余额（Customer Balance）从预估金额中扣除，无需额外配置。
• 优惠券应用逻辑：如果客户账户已设置全局优惠券（customer.coupon），会自动应用到新订阅的发票；如果是原订阅专属的优惠券，需要手动通过coupon参数指定。
• Prorate 计算：设置subscription_proration_behavior为create_prorations后，Stripe会计算原订阅剩余周期的未使用费用，将其作为信用额度抵扣新订阅的费用（升级时补差价，降级时退余额）。
• Price ID 替代 Plan ID：Stripe目前推荐使用更灵活的Price ID（每个Plan对应至少一个Price），支持多货币、不同计费周期等场景，建议替换你的Plan ID为Price ID来调用。

降级场景的适配 #

如果是跨周期降级（比如从年度订阅降到月度），逻辑完全一致：只需要将subscription_items中的Price ID替换为降级后的月度套餐即可，Stripe会自动计算原订阅剩余周期的费用并转为客户余额，抵扣新订阅的费用。

内容的提问来源于stack exchange，提问作者Adam M.