如何实现Stripe订阅1年后自动取消？含首月额外收费场景

一、实现订阅1年后自动取消 #

有两种可靠方案可确保订阅在12个月后自动终止：

方案1：直接设置订阅cancel_at时间戳 #

在创建Checkout Session时，通过subscription_data参数指定1年后的时间戳，Stripe会在该时间点自动取消订阅。

修改后代码如下：

import datetime

# 计算1年后的时间戳
one_year_later = datetime.datetime.now() + datetime.timedelta(days=365)
cancel_at_timestamp = int(one_year_later.timestamp())

checkout_session = stripe.checkout.Session.create(
    payment_method_types=["card"],
    mode="subscription",
    customer=stripe_customer_id,
    line_items=[
        {
            "price": product.stripe_recurring_price_id,
            "quantity": 1,
        },
        {
            # 首月额外费用
            "price_data": {
                "currency": "myr",
                "product": "PRODUCT_ID",
                "unit_amount": 4000,
                "recurring": None,
            },
            "quantity": 1,
        },
    ],
    metadata=metadata,
    # 添加订阅自动取消配置
    subscription_data={
        "cancel_at": cancel_at_timestamp
    },
    success_url=YOUR_DOMAIN + "success?success=true",
    cancel_url=YOUR_DOMAIN + "success?canceled=true",
)
return JsonResponse({"id": checkout_session.id, "url": checkout_session.url})

方案2：使用订阅日程（Subscription Schedule） #

如果订阅是固定周期（如月付），通过订阅日程设置仅运行12个周期，结束后自动取消，这种方式更贴合订阅周期逻辑：

# 先创建订阅日程，设置12个周期后自动取消
schedule = stripe.SubscriptionSchedule.create(
    customer=stripe_customer_id,
    start_date="now",
    phases=[
        {
            "items": [
                {
                    "price": product.stripe_recurring_price_id,
                    "quantity": 1,
                }
            ],
            "iterations": 12,  # 运行12个订阅周期（月付即12个月）
        }
    ],
    end_behavior="cancel"  # 周期结束后自动取消订阅
)

# 创建Checkout Session时关联该日程
checkout_session = stripe.checkout.Session.create(
    payment_method_types=["card"],
    mode="subscription",
    customer=stripe_customer_id,
    line_items=[
        {
            "price": product.stripe_recurring_price_id,
            "quantity": 1,
        },
        {
            # 首月额外费用
            "price_data": {
                "currency": "myr",
                "product": "PRODUCT_ID",
                "unit_amount": 4000,
                "recurring": None,
            },
            "quantity": 1,
        },
    ],
    metadata=metadata,
    subscription_data={
        "schedule": schedule.id
    },
    success_url=YOUR_DOMAIN + "success?success=true",
    cancel_url=YOUR_DOMAIN + "success?canceled=true",
)
return JsonResponse({"id": checkout_session.id, "url": checkout_session.url})

二、首月额外收费的替代方案 #

你当前在Checkout Session中添加一次性line item的方法是可行的，另外还有两种替代方案：

• 方案1：创建包含首月溢价的分层价格
  针对订阅产品创建一个价格，设置首月价格为「订阅价+额外费」，后续月份恢复正常订阅价。通过价格的recurring.initial_phase配置实现：

  # 创建首月溢价的价格
  premium_price = stripe.Price.create(
      currency="myr",
      product="SUBSCRIPTION_PRODUCT_ID",
      unit_amount=正常订阅价（分）,
      recurring={
          "interval": "month",
          "initial_phase": {
              "iterations": 1,
              "unit_amount": 正常订阅价+4000（分）,
              "interval": "month"
          }
      }
  )
  

  之后在Checkout Session的line items中直接使用这个价格即可，无需额外添加一次性项。

• 方案2：订阅创建后添加一次性发票项
  监听checkout.session.completed webhook，在订阅成功创建后，给首次账单添加一次性费用：

  # 在webhook处理函数中
  if event["type"] == "checkout.session.completed":
      session = event["data"]["object"]
      subscription_id = session["subscription"]
      # 添加一次性费用到订阅的首次账单
      stripe.InvoiceItem.create(
          customer=session["customer"],
          subscription=subscription_id,
          price_data={
              "currency": "myr",
              "product": "PRODUCT_ID",
              "unit_amount": 4000,
              "recurring": None
          }
      )
      # 触发账单生成
      invoice = stripe.Invoice.list(customer=session["customer"], subscription=subscription_id).data[0]
      stripe.Invoice.pay(invoice.id)
  

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