创建Stripe Checkout Session时遇backdate_start_date参数未知错误求助

我尝试创建用于订阅的Stripe Checkout Session，但遇到错误提示：

Error processing payment: Received unknown parameter: subscription_data[backdate_start_date]

相关代码如下：

public function createCheckoutSession($customerId, $priceId, $isSubscription = false)
{
    $now = Carbon::parse('2024-03-01');
    $financialYearStart = Carbon::createFromDate($now->year, 7, 1);
    $financialYearEnd = Carbon::createFromDate($now->year + 1, 6, 30);

    $sessionParams = [
        'payment_method_types' => ['card'],
        'customer' => $customerId,
        'line_items' => [[
            'price' => $priceId,
            'quantity' => 1,
        ]],
        'success_url' => url('https://test/payment/success?session_id={CHECKOUT_SESSION_ID}'),
        'cancel_url' => url('https://test/payment/cancel'),
        'mode' => $isSubscription ? 'subscription' : 'payment',
        'subscription_data' => [],
    ];

    if ($isSubscription) {
        if ($now->month == 6) {
            // User starts in June, calculate remaining days in June for trial period
            $trialEndDate = Carbon::createFromDate($now->year, 6, 30)->endOfDay();
            $sessionParams['subscription_data']['trial_end'] = $trialEndDate->timestamp;
        } else {
            // User starts before June, set the backdate start date
            $backdateStartDate = $financialYearStart->subYear()->timestamp;
            $billingCycleAnchor = $financialYearStart->timestamp;
            $sessionParams['subscription_data']['backdate_start_date'] = $backdateStartDate;
            $sessionParams['subscription_data']['billing_cycle_anchor'] = $billingCycleAnchor;
            Log::info('Setting backdate_start_date and billing_cycle_anchor for before June:', [
                'backdate_start_date' => $sessionParams['subscription_data']['backdate_start_date'],
                'billing_cycle_anchor' => $sessionParams['subscription_data']['billing_cycle_anchor']
            ]);
        }
    }
    Log::info('Stripe session params:', ['sessionParams' => $sessionParams]);
    return $this->stripe->checkout->sessions->create($sessionParams);
}

根据Stripe文档，backdate_start_date是创建订阅时的有效参数，请问为何会收到该错误，以及如何通过Stripe Checkout Session正确设置订阅的过去起始日期？

错误原因 #

backdate_start_date是**直接创建订阅（subscriptions.create接口）**的参数，并非Stripe Checkout Session创建接口（checkout.sessions.create）支持的subscription_data子参数。Checkout的subscription_data仅支持有限子集（如trial_end、metadata、description等），不包含回溯起始日期这类调整订阅周期的参数。

正确解决方案 #

要实现订阅回溯起始日期，需在Checkout成功创建订阅后，通过Webhook更新订阅：

1. 修改Checkout Session创建代码 #

• 移除subscription_data[backdate_start_date]参数，保留billing_cycle_anchor（该参数为Checkout支持）
• 在subscription_data[metadata]中存储回溯起始日期信息，方便后续Webhook调用时读取
• 修复Carbon对象引用问题：$financialYearStart->subYear()会直接修改原对象，导致后续billing_cycle_anchor值错误，改用copy()方法生成新对象

修改后的代码片段：

else {
    // User starts before June, set billing cycle anchor and store backdate info in metadata
    $backdateStartDate = $financialYearStart->copy()->subYear()->timestamp;
    $billingCycleAnchor = $financialYearStart->timestamp;
    $sessionParams['subscription_data']['billing_cycle_anchor'] = $billingCycleAnchor;
    // 存储回溯日期到metadata，方便Webhook读取
    $sessionParams['subscription_data']['metadata'] = [
        'backdate_start_date' => $backdateStartDate
    ];
    Log::info('Setting billing_cycle_anchor and backdate metadata for before June:', [
        'backdate_start_date' => $backdateStartDate,
        'billing_cycle_anchor' => $billingCycleAnchor
    ]);
}

2. 处理Checkout完成的Webhook #

当用户完成Checkout后，Stripe会发送checkout.session.completed事件，在该Webhook中获取已创建的订阅ID，调用subscriptions.update接口设置backdate_start_date：

public function handleStripeWebhook(Request $request)
{
    $payload = $request->getContent();
    $sigHeader = $request->header('Stripe-Signature');
    $event = $this->stripe->webhooks->constructEvent(
        $payload, $sigHeader, config('services.stripe.webhook_secret')
    );

    if ($event->type === 'checkout.session.completed') {
        $session = $event->data->object;
        // 仅处理订阅模式的会话
        if ($session->mode === 'subscription') {
            $subscriptionId = $session->subscription;
            $metadata = $session->subscription_data->metadata ?? [];
            if (isset($metadata['backdate_start_date'])) {
                $this->stripe->subscriptions->update(
                    $subscriptionId,
                    [
                        'backdate_start_date' => $metadata['backdate_start_date'],
                        // 可选：设置proration_behavior控制回溯产生的费用
                        'proration_behavior' => 'create_prorations'
                    ]
                );
            }
        }
    }

    return response()->json(['status' => 'success']);
}

3. 注意事项 #

• 确保Webhook已在Stripe Dashboard中配置并能正常接收事件
• 根据业务需求设置proration_behavior参数，控制回溯订阅产生的 prorated 费用（如none不生成额外费用，create_prorations生成费用）
• 回溯起始日期必须早于订阅创建日期，且在订阅价格的计费周期范围内

内容的提问来源于stack exchange，提问作者3RS GT