在 Stripe 的开发过程中，更新 Subscription 是一个常见的需求。尽管 Stripe API 使用相对简单，但由于账单日期或订阅类型的限制，有时我们无法立即更新 Subscription。这时，Subscription Schedule 功能就显得尤为重要，它允许我们在未来的特定时间创建或更新订阅。
Subscription Schedule 的功能与挑战
Subscription Schedule 是 Stripe 提供的一种强大功能，但在实际应用中，开发者可能会遇到一些困惑。尽管 Stripe 提供了详细的 API 文档 和 使用案例，但由于 API 的不断演进，一些新对象和字段的引入与废弃可能会让人感到困惑。例如，Price 已经取代了 Plan，而在 Phase Items 中，coupon 字段已被弃用。
本文将分享一个实际案例，探讨如何在未来的某个时间点更新 Subscription Item 的数量，同时保留原有的 coupon 有效期。我们还将讨论开发过程中遇到的挑战及解决方案。
案例场景
假设我们有一个 Subscription，其中包含一个 Subscription Item – SaaS Member Fee，单价为 $10，数量为 5，并且附带一个三个月的免费 coupon。我们的目标是在 9 月 1 日将该数量更新为 10。
Stripe 的实现方式
即使有详细的 API 文档和使用案例，初次对接 Subscription Schedule API 仍可能让人感到困惑。我们需要创建一个 Subscription Schedule，但参数的传递方式并不总是直观明了。
Stripe 自身在进行 Schedule Update 时，通常会进行两次 API 调用。首先，创建 Subscription Schedule 仅传递 from_subscription 参数；然后，利用返回的 Schedule ID 进行第二次 API 调用，传入大量参数以完成具体的配置。
Phase 的核心概念
Phase 代表 Subscription Schedule 中的一段特定时间，其间应用指定的计费参数。每个 Phase 都有以下关键参数：
- start_date 和 end_date：标识 Phase 的开始和结束日期。
- price 和 quantity：指定订阅项目的价格和数量。
- discounts：在该 Phase 中使用的折扣或优惠券。
- tax_rates 和 automatic_tax：税率相关参数。
- collection_method 等。
在本文的案例中，Stripe 设置了三个 Phase 来实现订阅数量的更新。
proration 与 proration_behavior 的解释
当订阅计划发生变化时，可能会涉及按比例调整账单金额，即 proration。Stripe 提供了 proration_behavior 参数来控制这一行为，其选项包括 create_prorations、none 和 always_invoice。
end_behavior 的作用
end_behavior 决定 Schedule 结束时 Subscription 的处理方式，可选值为 release 或 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’
结语
通过 Stripe 的 Subscription Schedule 功能，我们可以更灵活地管理订阅。虽然初次使用时可能会遇到一些挑战，但通过深入了解和实践，这一工具将极大地简化订阅管理流程。希望本文能为开发者提供有价值的参考。