如何通过Python API更新Stripe订阅且不累积Price对象

核心问题在于你调用Subscription.modify时只传入了新的price参数，Stripe默认行为是新增一个订阅项而非替换原有项，导致计费时同时收取新旧两个Price的费用。以下是两种简单可行的解决方案：

方案一：直接替换现有订阅项（推荐） #

通过指定原订阅项的id，告诉Stripe要更新这个项的Price，而非新增。同时配置proration_behavior确保新费用在下次计费周期收取：

# 获取订阅对象并展开订阅项列表
subscription = stripe.Subscription.retrieve(
    "<stripe_subscription_id>",
    expand=["items.data"]
)

# 获取原订阅的第一个项目ID（如果有多个项，可根据业务逻辑筛选目标项）
original_item_id = subscription["items"]["data"][0]["id"]

# 修改订阅：替换原项的Price，设置下次计费生效
mod_subscription = stripe.Subscription.modify(
    "<stripe_subscription_id>",
    items=[{
        "id": original_item_id,
        "price": "<stripe_price_id>"
    }],
    proration_behavior="none"  # 禁止立即收取差价，新费用下次计费时结算
)

方案二：清空所有旧项再添加新项（适合多订阅项场景） #

如果需要替换所有现有订阅项，可以先删除旧项再添加新项：

# 获取订阅对象
subscription = stripe.Subscription.retrieve(
    "<stripe_subscription_id>",
    expand=["items.data"]
)

# 构建修改参数：删除所有旧项 + 添加新项
modify_items = []
# 遍历所有旧订阅项，标记为删除
for item in subscription["items"]["data"]:
    modify_items.append({"id": item["id"], "deleted": True})
# 添加新的订阅项
modify_items.append({"price": "<stripe_price_id>"})

# 执行修改
mod_subscription = stripe.Subscription.modify(
    "<stripe_subscription_id>",
    items=modify_items,
    proration_behavior="none"
)

关键注意点 #

• proration_behavior="none"是必须的：这个参数会阻止Stripe立即按比例收取新旧订阅的差价，确保新费用完全在下次计费周期收取
• 筛选订阅项时：如果订阅包含多个固定项，不要盲目替换第一个，要根据业务逻辑（比如产品类型）筛选需要更新的项
• 测试建议：先用Stripe测试模式验证流程，避免产生真实扣费

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