Stripe fixed-price subscription运作流程、更新、扣款规则及NodeJS示例咨询
Stripe固定价格订阅运作逻辑与实操参考
一、固定价格订阅完整工作流程
- 前置准备:在Stripe侧创建绑定固定金额、计费周期的
Price对象(关联对应售卖产品),配置好账单通知、扣款失败重试、Webhook回调规则,不需要自定义计价逻辑。 - 订阅发起:前端通过Stripe Elements收集用户支付信息,生成
PaymentMethod对象传给后端;后端将该支付方式绑定到对应的Customer对象,调用订阅创建接口关联目标Price,配置试用期、优惠码等可选参数。 - 自动流转:订阅创建完成后Stripe自动维护全生命周期状态,在每个计费节点生成对应账单,完成扣款后触发
invoice.paid、customer.subscription.updated等Webhook事件,商户系统可基于事件同步本地订单状态。 - 生命周期管理:支持中途修改支付方式、调整价格、变更计费周期、暂停/取消订阅,所有变更会按照设置的生效节点自动更新后续账单规则,不需要手动触发月度/年度的扣款动作。
二、已创建订阅的核心操作逻辑
- 信用卡详情更新:本质是修改关联
Customer对象的默认支付方式,不需要改动订阅本身的配置,后续该客户名下所有订阅的扣款都会自动使用新的支付方式;如果客户存在未结清的逾期账单,更新支付方式后Stripe会自动触发历史欠缴账单的扣款流程。 - 订阅价格调整:固定价格模式下调整价格,核心是替换订阅条目上绑定的
Price对象ID,支持两种生效逻辑:① 即时生效:按当前周期剩余时长折算新旧价格的差价,生成即时账单完成补扣或退费;② 下个计费周期生效:不产生即时账单,当前周期结束后自动按新价格计费。 - 计费周期修改:调整订阅关联
Price的计费间隔(如月付改季付、季付改年付),同样支持“即时折算差价生效”和“下周期自动生效”两种模式,修改完成后Stripe会自动重新计算后续所有周期的扣款时间锚点。
三、订阅扣款规则说明
不存在固定的“用户发起订阅时立即扣款/首个周期结束后扣款”的通用规则,扣款时间完全由创建订阅时的参数决定:
- 无免费试用期的场景:订阅创建完成的瞬间就会生成首个周期的账单,即时完成扣款。
- 配置了免费试用期的场景:整个试用期内不会发起扣款,直到试用期结束、进入首个正式计费周期的时间点才会触发首次扣款。
- 中途变更配置的场景:如果选择“下周期生效”的调整模式,不会在修改操作发生时立刻扣款,仅在对应周期节点生成账单扣款;如果选择即时生效,会立刻生成差价账单完成折算扣款。
- 扣款失败场景:Stripe会按照提前配置的重试频率,在后续1-2周内反复尝试扣款,直到账单结清或达到最大重试次数后将订阅标记为逾期。
四、对应操作的Node.js代码示例
前置依赖:先安装Stripe官方Node SDK,初始化客户端实例:
const Stripe = require('stripe'); // 替换为你的Stripe后台密钥 const stripe = new Stripe('sk_xxxxxx');
- 基础固定价格订阅创建
const createFixedPriceSubscription = async (customerId, fixedPriceId, paymentMethodId) => { // 将收集到的支付方式绑定到客户 await stripe.paymentMethods.attach(paymentMethodId, { customer: customerId }); // 设置为客户的默认扣款方式 await stripe.customers.update(customerId, { invoice_settings: { default_payment_method: paymentMethodId } }); // 创建固定价格订阅 return stripe.subscriptions.create({ customer: customerId, items: [{ price: fixedPriceId }], payment_behavior: 'default_incomplete', expand: ['latest_invoice.payment_intent'] }); };
- 更新订阅关联的信用卡详情
const updateSubscriptionCard = async (customerId, newPaymentMethodId) => { // 绑定新卡到客户 await stripe.paymentMethods.attach(newPaymentMethodId, { customer: customerId }); // 更新默认支付方式 await stripe.customers.update(customerId, { invoice_settings: { default_payment_method: newPaymentMethodId } }); // 自动结清客户名下所有未支付的开放账单 const openInvoices = await stripe.invoices.list({ customer: customerId, status: 'open' }); for (const invoice of openInvoices.data) { await stripe.invoices.pay(invoice.id, { payment_method: newPaymentMethodId }); } };
- 调整订阅价格
const adjustSubscriptionPrice = async (subscriptionId, newPriceId, applyImmediately = false) => { const currentSubscription = await stripe.subscriptions.retrieve(subscriptionId); const currentItemId = currentSubscription.items.data[0].id; return stripe.subscriptions.update(subscriptionId, { items: [{ id: currentItemId, price: newPriceId }], // 即时生效时开启差价折算,下周期生效时不生成即时账单 proration_behavior: applyImmediately ? 'create_prorations' : 'none', payment_behavior: 'default_incomplete' }); };
- 修改订阅计费周期
const changeBillingCycle = async (subscriptionId, newCyclePriceId, applyNextCycle = true) => { const currentSubscription = await stripe.subscriptions.retrieve(subscriptionId); const currentItemId = currentSubscription.items.data[0].id; return stripe.subscriptions.update(subscriptionId, { items: [{ id: currentItemId, price: newCyclePriceId }], // 下周期生效时保持原计费锚点,不即时折算差价 proration_behavior: applyNextCycle ? 'none' : 'create_prorations', billing_cycle_anchor: applyNextCycle ? 'unchanged' : 'now' }); };
内容的提问来源于stack exchange,提问作者Venkatraman
相关产品推荐
相关产品推荐

