前言：为什么需要 Subscription Schedule？

在使用 Stripe API 更新订阅(Subscription) 时，开发者通常会遇到一个常见问题：由于账单日期或产品订阅类型的限制，我们无法立即更新订阅。这时，Stripe 的 Subscription Schedule 功能就派上了用场，它允许我们在未来的某个时间点创建或更新订阅。

Subscription Schedule：功能强大但易混淆

虽然 Stripe 提供了详细的 API 文档和 Use Cases，但随着 API 的不断迭代，开发者仍可能遇到困惑。比如：

Price 取代了 Plan
Phase Items 中弃用了 coupon 字段
新旧版本的字段共存，增加理解难度

本文将分享一个实际案例：如何安排在未来某个时间点更新订阅项(Subscription Item)的数量，同时保留原优惠券(coupon)的有效期。

实际应用场景

假设我们有一个订阅，包含以下信息：

订阅项：SaaS 会员费
单价：$10
数量：5
优惠券：3个月免费

我们的目标是在9月1日将订阅数量更新为10，同时保留原有的优惠券。

Stripe API 的调用逻辑

当我们需要创建一个 Subscription Schedule 时，Stripe 官方文档提供的示例如下：

ruby Stripe::SubscriptionSchedule.create({ customer: 'cus_NcI8FsMbh0OeFs', start_date: 1680716828, end_behavior: 'release', phases: [ { items: [ { price: 'price_1Mr3YcLkdIwHu7ixYCFhXHNb', quantity: 1, }, ], iterations: 12, }, ], })

然而，在实际应用中，我们可能需要修改现有订阅。这时，from_subscription 参数就会派上用场。但需要注意的是：

当使用 from_subscription 参数时，其他参数（如 phase 值）将无法设置。因此，建议通过两次独立的 API 调用来创建订阅计划。

核心概念解析

1. Phase（阶段）

Phase 定义了订阅计划中的特定时间段，每个阶段都可以设置不同的计费参数：

起止时间：每个阶段的开始和结束日期
价格和数量：可为订阅项指定不同的价格和数量
优惠折扣：应用特定的折扣或优惠券

2. Proration（按比例调整）

当订阅计划发生变化时（如调整数量），Stripe 会自动进行按比例调整。通过 proration_behavior 参数，我们可以指定其行为：

create_prorations：默认值，自动创建按比例调整
none：不进行按比例调整
always_invoice：立即创建按比例调整的账单

3. End Behavior（结束行为）

end_behavior 参数定义了 Schedule 结束时的操作：

release：默认值，Subscription 保持当前状态继续
cancel：Subscription 直接取消

完整解决方案

以下是在未来某个时间点更新订阅数量的完整代码实现：

ruby schedule = Stripe::SubscriptionSchedule.create from_subscription: subscription.id

phase0 = schedule.phases[0] phase0_item = phase0.items[0]

original_quantity = phase0_item.quantity price_id = phase0_item.price discounts = phase0.discounts.collect(&:to_hash)

phases = [

Phase 0 - 修改现有订阅阶段，结束日期为 `time`

{ start_date: phase0.start_date, end_date: time.to_i, proration_behavior: 'none', discounts: discounts, items: [ { price: price_id, quantity: original_quantity, } ] },

Phase 1 - 设置一个新的订阅阶段，开始日期为 `time`，数量为 `quantity`

{ start_date: time.to_i, end_date: time.to_i + 60, proration_behavior: 'none', discounts: discounts, items: [ { price: price_id, quantity: quantity, } ] } ]

Stripe::SubscriptionSchedule.update schedule.id, phases: phases, proration_behavior: 'none'