Back to Details

stripe-billing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Stripe Billing

Stripe Billing

Implement subscriptions, invoicing, and flexible pricing models for recurring revenue.
为经常性收入实现订阅、发票和灵活定价模型。

Rule Priority

规则优先级

PriorityRuleImpactDescription
1
sub-use-checkout-for-creation
HIGHCreate subscriptions via Checkout for built-in payment collection, SCA, and tax
2
sub-check-payment-behavior
HIGHUse 
default_incomplete
for SCA-compliant API-created subscriptions
3
sub-expand-latest-invoice
HIGHExpand 
latest_invoice.payment_intent
to get client secret in one call
4
webhook-verify-signatures
HIGHAlways verify webhook signatures to prevent forged events
5
webhook-handle-subscription-updated
HIGHSync state on every 
subscription.updated
for plan changes, cancellations, status
6
invoice-listen-paid-event
HIGHUse 
invoice.paid
(not 
payment_intent.succeeded
) for subscription fulfillment
7
webhook-idempotent-handlers
HIGHDesign handlers for at-least-once delivery with event deduplication
8
webhook-return-200-quickly
HIGHAcknowledge webhooks immediately, process asynchronously
9
price-use-lookup-keys
HIGHUse 
lookup_key
for price references instead of hardcoded IDs
10
dunning-enable-smart-retries
HIGHEnable ML-powered Smart Retries for optimal payment recovery
11
sub-cancel-at-period-end
HIGHCancel at period end for better UX and win-back opportunity
12
trial-collect-payment-method
HIGHCollect payment method during trial for higher conversion
13
usage-report-idempotently
HIGHInclude idempotency keys with usage records to prevent double-counting
14
usage-flush-before-period-end
HIGHFlush usage buffers before period end to prevent revenue leakage
15
portal-configure-allowed-products
HIGHExplicitly list products/prices in portal configuration
16
price-use-decimal-for-subcent
HIGHUse 
unit_amount_decimal
for sub-cent pricing
17
invoice-preview-before-changes
MEDIUMPreview upcoming invoice before applying subscription changes
18
trial-handle-will-end-webhook
MEDIUMHandle 
trial_will_end
for pre-expiry reminders
19
usage-prefer-billing-meters
MEDIUMUse Billing Meters over legacy usage records for new integrations
20
portal-use-deep-links
MEDIUMUse 
flow_data
for targeted portal actions
21
sub-pause-not-cancel
MEDIUMPause subscriptions instead of canceling for temporary stops
22
dunning-escalate-communications
MEDIUMEscalate dunning communications over retry attempts
23
price-deactivate-not-delete
MEDIUMDeactivate old prices instead of deleting them
优先级规则影响程度描述
1
sub-use-checkout-for-creation
HIGH通过Checkout创建订阅，以利用内置的收款、SCA和税务功能
2
sub-check-payment-behavior
HIGH对于通过API创建的订阅，使用
default_incomplete
以符合SCA要求
3
sub-expand-latest-invoice
HIGH展开
latest_invoice.payment_intent
，通过一次调用获取客户端密钥
4
webhook-verify-signatures
HIGH始终验证Webhook签名，防止伪造事件
5
webhook-handle-subscription-updated
HIGH在每次
subscription.updated
事件时同步状态，处理计划变更、取消、状态转换等
6
invoice-listen-paid-event
HIGH使用
invoice.paid
（而非
payment_intent.succeeded
）来确认订阅服务的交付
7
webhook-idempotent-handlers
HIGH设计支持至少一次交付的处理器，实现事件去重
8
webhook-return-200-quickly
HIGH立即确认Webhook请求，异步处理业务逻辑
9
price-use-lookup-keys
HIGH使用
lookup_key
引用价格，而非硬编码ID
10
dunning-enable-smart-retries
HIGH启用基于机器学习的智能重试功能，优化付款回收率
11
sub-cancel-at-period-end
HIGH在计费周期结束时取消订阅，以获得更好的用户体验和赢回客户的机会
12
trial-collect-payment-method
HIGH在试用期间收集付款方式，提高转化率
13
usage-report-idempotently
HIGH在使用记录中包含幂等键，防止重复统计
14
usage-flush-before-period-end
HIGH在计费周期结束前刷新使用量缓冲区，防止收入流失
15
portal-configure-allowed-products
HIGH在门户配置中明确列出允许的产品/价格
16
price-use-decimal-for-subcent
HIGH对于低于1美分的定价，使用
unit_amount_decimal
17
invoice-preview-before-changes
MEDIUM在应用订阅变更前预览即将生成的发票
18
trial-handle-will-end-webhook
MEDIUM处理
trial_will_end
事件，发送试用到期提醒
19
usage-prefer-billing-meters
MEDIUM对于新集成，优先使用Billing Meters而非旧版使用记录
20
portal-use-deep-links
MEDIUM使用
flow_data
实现定向门户操作
21
sub-pause-not-cancel
MEDIUM对于临时停用的情况，暂停订阅而非直接取消
22
dunning-escalate-communications
MEDIUM在重试付款过程中逐步升级催款沟通方式
23
price-deactivate-not-delete
MEDIUM停用旧价格而非删除它们

Pricing Model Decision Tree

定价模型决策树

What pricing model fits your product?
|
+-- Fixed monthly/annual fee?
|   -> Flat-rate pricing (references/pricing-models.md)
|
+-- Per-seat / per-unit?
|   -> Per-unit pricing (references/pricing-models.md)
|
+-- Volume tiers (price decreases with quantity)?
|   -> Tiered pricing (references/pricing-models.md)
|
+-- Pay for what you use (API calls, storage)?
|   -> Usage-based / metered (references/usage-based.md)
|
+-- Hybrid (base fee + usage)?
    -> Multiple prices on one subscription (references/pricing-models.md)
你的产品适合哪种定价模型？
|
+-- 固定月费/年费？
|   -> 固定费率定价（references/pricing-models.md）
|
+-- 按席位/按单位？
|   -> 按单位定价（references/pricing-models.md）
|
+-- 阶梯式定价（购买量越大单价越低）？
|   -> 分层定价（references/pricing-models.md）
|
+-- 按使用量付费（API调用、存储等）？
|   -> 基于使用量/计量计费（references/usage-based.md）
|
+-- 混合模式（基础费用+使用量费用）？
    -> 单个订阅关联多个价格（references/pricing-models.md）

Quick Start: SaaS Subscription

快速开始：SaaS订阅

1. Create Product + Price (once, or via Dashboard)

1. 创建产品+价格（一次性操作，或通过控制台完成）

typescript
const product = await stripe.products.create({
  name: 'Pro Plan',
  description: 'Full access to all features',
});

const price = await stripe.prices.create({
  product: product.id,
  unit_amount: 2900, // $29/month
  currency: 'usd',
  recurring: { interval: 'month' },
  lookup_key: 'pro_monthly',
});
typescript
const product = await stripe.products.create({
  name: 'Pro Plan',
  description: 'Full access to all features',
});

const price = await stripe.prices.create({
  product: product.id,
  unit_amount: 2900, // $29/月
  currency: 'usd',
  recurring: { interval: 'month' },
  lookup_key: 'pro_monthly',
});

2. Create Subscription via Checkout

2. 通过Checkout创建订阅

typescript
const session = await stripe.checkout.sessions.create({
  customer: 'cus_xxx', // or let Checkout create one
  line_items: [{ price: price.id, quantity: 1 }],
  mode: 'subscription',
  success_url: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
  cancel_url: 'https://example.com/cancel',
});
typescript
const session = await stripe.checkout.sessions.create({
  customer: 'cus_xxx', // 或让Checkout自动创建客户
  line_items: [{ price: price.id, quantity: 1 }],
  mode: 'subscription',
  success_url: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
  cancel_url: 'https://example.com/cancel',
});

3. Or Create Subscription Directly (with existing payment method)

3. 或直接创建订阅（使用已有的付款方式）

typescript
const subscription = await stripe.subscriptions.create({
  customer: 'cus_xxx',
  items: [{ price: price.id }],
  default_payment_method: 'pm_xxx',
  payment_behavior: 'default_incomplete', // requires client confirmation
  expand: ['latest_invoice.payment_intent'],
});
// Return subscription.latest_invoice.payment_intent.client_secret to frontend
typescript
const subscription = await stripe.subscriptions.create({
  customer: 'cus_xxx',
  items: [{ price: price.id }],
  default_payment_method: 'pm_xxx',
  payment_behavior: 'default_incomplete', // 需要客户端确认
  expand: ['latest_invoice.payment_intent'],
});
// 将subscription.latest_invoice.payment_intent.client_secret返回给前端

Subscription Lifecycle

订阅生命周期

incomplete -> active -> past_due -> canceled
                     -> canceled (immediate)
                     -> paused
trialing -> active (payment succeeds)
        -> incomplete (payment fails)
        -> canceled (trial ends, no payment method)
incomplete -> active -> past_due -> canceled
                     -> canceled (立即取消)
                     -> paused
trialing -> active (付款成功)
        -> incomplete (付款失败)
        -> canceled (试用结束，无付款方式)

Customer Portal (Self-Service)

客户门户（自助服务）

typescript
// One-time setup in Dashboard or API
const configuration = await stripe.billingPortal.configurations.create({
  features: {
    subscription_update: { enabled: true, products: [{ product: 'prod_xxx', prices: ['price_basic', 'price_pro'] }] },
    subscription_cancel: { enabled: true, mode: 'at_period_end' },
    payment_method_update: { enabled: true },
    invoice_history: { enabled: true },
  },
});

// Generate portal session per customer
const portalSession = await stripe.billingPortal.sessions.create({
  customer: 'cus_xxx',
  return_url: 'https://example.com/account',
});
// Redirect to portalSession.url
typescript
// 在控制台或API中完成一次性配置
const configuration = await stripe.billingPortal.configurations.create({
  features: {
    subscription_update: { enabled: true, products: [{ product: 'prod_xxx', prices: ['price_basic', 'price_pro'] }] },
    subscription_cancel: { enabled: true, mode: 'at_period_end' },
    payment_method_update: { enabled: true },
    invoice_history: { enabled: true },
  },
});

// 为每个客户生成门户会话
const portalSession = await stripe.billingPortal.sessions.create({
  customer: 'cus_xxx',
  return_url: 'https://example.com/account',
});
// 重定向到portalSession.url

Critical Webhooks

关键Webhook事件

EventAction
customer.subscription.created
Provision access
customer.subscription.updated
Handle plan changes, cancellation scheduling, status transitions
customer.subscription.deleted
Revoke access
customer.subscription.trial_will_end
Remind user (3 days before)
invoice.paid
Confirm payment, extend access
invoice.payment_failed
Notify user, trigger dunning escalation
invoice.upcoming
Preview next charge
事件操作
customer.subscription.created
开通服务权限
customer.subscription.updated
处理计划变更、取消安排、状态转换
customer.subscription.deleted
收回服务权限
customer.subscription.trial_will_end
提醒用户（到期前3天）
invoice.paid
确认付款，延长服务权限
invoice.payment_failed
通知用户，触发催款升级流程
invoice.upcoming
预览下一次收费

Quick Reference

快速参考

TopicKey ConceptReference
Flat/tiered pricingProducts have multiple Prices; use 
lookup_key
references/pricing-models.md
Subscription creationPrefer Checkout; use 
default_incomplete
for API		references/subscription-lifecycle.md
Usage billingBilling Meters (modern) or Usage Records (legacy)references/usage-based.md
Trials
trial_period_days
or 
trial_end
; collect payment method		references/trials.md
Invoices
invoice.paid
is authoritative; preview before changes		references/invoices.md
Customer portalConfigure products explicitly; use deep linksreferences/customer-portal.md
DunningSmart Retries + escalating communicationsreferences/dunning.md
CouponsCoupons (internal) + Promotion Codes (customer-facing)references/coupons.md
Proration
always_invoice
for immediate; 
none
for period-end		references/proration.md
SchedulesPhase-based automation; max 10 phasesreferences/schedules.md
主题核心概念参考文档
固定/分层定价产品可关联多个Price；使用
lookup_key
references/pricing-models.md
订阅创建优先使用Checkout；API创建时使用
default_incomplete
references/subscription-lifecycle.md
使用量计费Billing Meters（现代方案）或使用记录（旧版）references/usage-based.md
试用
trial_period_days
或
trial_end
；收集付款方式		references/trials.md
发票
invoice.paid
为权威事件；变更前预览		references/invoices.md
客户门户明确配置允许的产品；使用深度链接references/customer-portal.md
催款智能重试+逐步升级的沟通方式references/dunning.md
优惠券优惠券（内部）+促销代码（面向客户）references/coupons.md
按比例计费
always_invoice
立即计费；
none
周期结束时计费		references/proration.md
订阅计划基于阶段的自动化；最多10个阶段references/schedules.md

References

参考文档

  • references/pricing-models.md - Flat, tiered, per-unit, graduated, volume pricing
  • references/subscription-lifecycle.md - Create, update, cancel, pause, resume
  • references/usage-based.md - Metered billing, usage records, aggregation
  • references/trials.md - Free trials with/without payment method, trial conversions
  • references/invoices.md - Invoice generation, customization, hosted page
  • references/customer-portal.md - Self-service configuration and customization
  • references/dunning.md - Smart retries, failed payment emails, recovery
  • references/coupons.md - Coupons, promotion codes, discounts
  • references/proration.md - Mid-cycle upgrades/downgrades, proration behavior
  • references/schedules.md - Subscription schedules for future changes
  • references/pricing-models.md - 固定费率、分层、按单位、梯度、批量定价
  • references/subscription-lifecycle.md - 创建、更新、取消、暂停、恢复
  • references/usage-based.md - 计量计费、使用记录、聚合
  • references/trials.md - 带/不带付款方式的免费试用、试用转换
  • references/invoices.md - 发票生成、自定义、托管页面
  • references/customer-portal.md - 自助服务配置和自定义
  • references/dunning.md - 智能重试、付款失败邮件、恢复
  • references/coupons.md - 优惠券、促销代码、折扣
  • references/proration.md - 周期内升级/降级、按比例计费行为
  • references/schedules.md - 用于未来变更的订阅计划