如何配置Stripe订阅计费周期：一次性3个月免费延长后恢复年付

要实现用户支付1年费用获得15个月服务、后续自动恢复1年计费周期的需求，需分两步完成：

1. 修改结账会话代码，添加延长标记 #

在创建订阅时保留原1年价格的计费配置，同时添加metadata标记，用于后续Webhook识别需要执行周期延长操作：

class CreateCheckoutSessionView(View):
    def post(self, request, *args, **kwrgs):
        ...
        
        checkout_session = stripe.checkout.Session.create(
                success_url=protocol + domain + reverse('payment_success')+'?session_id={CHECKOUT_SESSION_ID}',
                cancel_url = protocol + domain + reverse('payment_failed'),
                payment_method_types=['card'],
                mode='subscription',
                customer=customer.id,
                line_items=[{
                    'price': price_id,  # 传入1年周期的价格ID
                    'quantity': 1,
                }],
                allow_promotion_codes = True,
                subscription_data={
                    'default_tax_rates': [STRIP_TAX_ID],
                    # 添加标记，告知Webhook需执行3个月周期延长
                    'metadata': {
                        'extend_3months': 'true'
                    }
                },
                # 强制立即收费，无试用阶段
                payment_intent_data={
                    'setup_future_usage': 'off_session'
                }
            )
        return redirect(checkout_session.url, code=303)

2. 通过Webhook处理订阅延长逻辑 #

监听Stripe的customer.subscription.created事件，识别标记后动态延长订阅周期3个月：

import stripe
from datetime import timedelta

def handle_subscription_created(event):
    subscription = event.data.object
    # 检查订阅是否需要执行3个月延长
    if subscription.metadata.get('extend_3months') == 'true':
        # 计算新的计费锚点：原周期结束时间 + 3个月（用90天近似，可替换为dateutil.relativedelta实现精准月数计算）
        new_anchor = subscription.current_period_end + 90 * 24 * 60 * 60
        
        # 修改订阅，延长第一个计费周期至15个月
        stripe.Subscription.modify(
            subscription.id,
            billing_cycle_anchor=new_anchor,
            proration_behavior='none',  # 不产生额外费用
            payment_behavior='default_incomplete'
        )
        
        # 移除标记，避免重复执行延长操作
        stripe.Subscription.modify(
            subscription.id,
            metadata={'extend_3months': ''}
        )

关键逻辑说明 #

• 立即收费：通过原1年价格的订阅配置实现，结账时直接扣除1年费用，无试用等待期
• 周期延长：通过修改billing_cycle_anchor将订阅首个周期从1年延长至15个月，后续周期会自动恢复为原价格的1年计费规则
• 无额外费用：延长阶段不产生额外扣费，用户仅支付1年费用即可获得15个月服务

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