##看结论：v2 现在该怎么用？
Stripe 用量计费 v2 更像一套新计费目录，不是把老订阅里的 Price 换个名字。2026 年 5 月 24 日查看官方文档时，pricing plans 和 rate cards 仍标着 private preview，接入前要确认账户权限。
AI SaaS 最稳的做法是两层账本：产品侧保留实时 usage_ledger 和 credit_ledger，Stripe 侧用 meter event、rate card、pricing plan 和 credit grant 做账务结算。这样 token 余额、图片次数、API 调用、退款、补发和 invoice 才能互相对上。
| 接入问题 | 现在的判断 | 对 AI SaaS 的影响 |
|---|---|---|
| Pricing plans 是否 GA | 官方文档标注 private preview | 不要把它当成所有客户的默认迁移目标 |
/v2 怎么测试 | 用 sandbox，不能用传统 test mode | CI、种子数据、测试卡要按 sandbox 重建 |
| Customer Portal 能做什么 | Advanced 路径下 limited | 可做账务查看，不要承诺自助升级降级 |
| Credits 能抵扣什么 | 只适合符合条件的 meter usage | 不等于产品数据库里的 token 钱包 |
| 高频事件怎么上报 | 标准端点 1000 calls/sec，v2 stream 更高 | 先算峰值，再决定是否上 Meter Event Stream |
这篇按李辰的 Stripe 出海工具栈经验写，直接拆 AI SaaS 里最容易混掉的 4 个对象：meter 记事实，rate card 定价格，pricing plan 组套餐，credits 做账务抵扣。
Stripe v2 和老式订阅差在哪？
老式订阅的核心路径是 Product、Price、Subscription。它适合每月固定费、简单 seat、单一 metered price。AI SaaS 的问题更碎：基础月费、赠送额度、超额 token、图片张数、不同模型倍率、团队 seat 和 top-up 往往同时存在。
Stripe advanced usage-based billing 把这些拆成 pricing components。pricing plan 是套餐容器，rate card 负责用量价格，license fee 负责固定 recurring charge，service action 目前用于 recurring credit grant。
| 业务概念 | Stripe advanced 路径里的对象 | 例子 |
|---|---|---|
| 原始消耗 | Meter event | ai_tokens_used = 3000 |
| 聚合规则 | Meter | 按月汇总 token，或按事件 count |
| 可收费项目 | Metered item | GPT-4.1 token、图片生成、成功 API call |
| 用量价格 | Rate card rate | 每 1000 tokens $0.02，图片每张 $0.04 |
| 固定月费 | License fee | Pro plan $29/月 |
| 套餐组合 | Pricing plan | Pro 月费 + 赠送 credits + 超额计费 |
| 账务抵扣 | Service action / credit grant | 每月 $10 credits，限定抵扣 meter usage |
关键变化是版本化。Stripe 文档说明 pricing plan version 会固定客户订阅的套餐版本；rate card version 也能让新老客户留在不同价格。对 AI SaaS 来说，这比直接改旧 Price 更贴近现实，因为模型成本和套餐文案会频繁调整。
Pricing plan 该放哪些组件？
按商业模型选组件，不要一上来把三个组件都塞进去。Stripe 的 pricing plans 文档给了三个常见模型：pay as you go、real-time credit burndown with top-ups、flat fee and overages。
| AI SaaS 模型 | Pricing plan 组件 | 什么时候用 |
|---|---|---|
| 纯按量 | Rate card | API 产品、开发者工具、没有固定权益 |
| 充值后消耗 | Rate card + credits | 图片生成、语音转写、批处理任务 |
| 月费 + 超额 | Rate card + license fee | Pro/Team 套餐，每月固定收入 |
| 月费 + 赠送额度 + 超额 | Rate card + license fee + service action | 大多数成熟 AI SaaS |
一个 Pro 套餐可以这样建：$29/月 是 license fee；ai_tokens、image_generation、workflow_run 是 metered items；每个 metered item 的固定价、volume 价或 graduated 价在 rate card；每月赠送的 ，0 credits 通过 service action 创建 recurring credit grant。
不要把 pricing plan 当成产品权限系统。你的数据库仍要保存 plan_code、stripe_pricing_plan_id、pricing_plan_version、entitlements_version。Stripe 负责收费，产品侧负责实时准入，例如余额不足时是否停止生成。
Rate card 和 meter 怎么建才不会返工？
Meter 先记录「发生了什么」，rate card 再决定「怎么收费」。这两个对象混在一起，后面改价会很麻烦。
聊天产品可以把一次成功回复聚合成一个 meter event，而不是把每个 streaming chunk 都发给 Stripe。payload 里保留 model、workspace_id、request_id、input_tokens、output_tokens，用于本地对账和后续维度定价。
图片产品建议单独建 image_generation meter。图片的失败重试、分辨率、队列取消和人工退款逻辑都和 token 不同，硬折成 token 会让账单解释变得困难。
API 产品可以建 successful_api_calls 或 completed_workflow_runs，只在业务结果明确完成后写入 usage ledger。4xx 参数错误、用户取消、平台 5xx 是否收费，要在事件进入 outbox 前决定。
| Meter 设计 | 推荐做法 | 不推荐做法 |
|---|---|---|
| Event name | 用稳定业务名，如 ai_tokens_used | 用模型名做 event name，换模型就返工 |
| Aggregation | token 用 sum，调用次数用 count | 所有事件都按 sum 处理 |
| Dimensions | model、region、workspace、event_type | 把客户可见套餐名塞进原始事件 |
| 上报粒度 | 一次业务成功 = 一个 billable event | 每个 token chunk 一个 Stripe event |
| 本地关联 | 保存 Stripe identifier 和 request_id | 只在 Stripe 里找用量来源 |
Stripe 的 meter 配置文档提醒：meter 创建后，除 display name 外可改空间很小。独立开发者早期最该花时间的不是做漂亮套餐页，而是把 event name、aggregation、payload key 和本地 ledger 固定下来。
Credits 是余额、折扣还是账务抵扣？
AI SaaS 里「credits」至少有三层含义。第一层是产品余额，用户页面显示「剩余 430 credits」。第二层是成本抽象，比如 1 credit 约等于 1000 tokens。第三层才是 Stripe billing credits 或 credit grant，用来抵扣合格的 usage invoice line。
Stripe 的 billing credits 文档把 credit grants 放在 public preview，并列出明显限制：credit grants 可用于 prepaid 或 promotional usage-based products，不是礼品卡、不是通用 stored value，也不能用于第三方支付。
| Credit 类型 | 存放位置 | 主要作用 | 风险 |
|---|---|---|---|
| 产品 credits | 你的数据库 | 实时展示余额、控制生成权限 | 与 invoice 不一致 |
| 成本 credits | 计费服务 | 把 token、图片、调用折成统一单位 | 模型成本变化后规则难解释 |
| Stripe billing credits | Stripe Billing | 抵扣符合条件的 meter usage | 不适用于 licensed price 或 legacy usage records |
Stripe credit grant 的抵扣也有条件：invoice period、effective_at、expires_at、available balance、currency 都要匹配；它只适用于通过 Meters 上报的 metered subscription items。一次性 invoice item、licensed price、legacy Usage Records 都不在这个范围里。
还有一个很实用的限制：每个客户最多 100 个 unused credit grants。做 top-up 的产品不要每次小额补偿都创建一个独立 grant，最好在产品侧先合并业务原因，再把账务动作写进 Stripe。
Customer Portal 有哪些坑？
Advanced usage-based billing 的 Customer Portal 支持是 limited。Stripe 的 pricing plans 文档把 Portal 口径写得很窄：客户可以查看 pricing plan subscriptions，但不能在 Portal 里更新付款方式、取消 subscription，也不能 upgrade 或 downgrade pricing plan subscriptions。
这意味着你的自助订阅管理页不能只丢一个 Portal 链接了事。Portal 在这条链路里更像只读账单入口；付款方式更新、套餐切换、降级排队、credit top-up、团队 seat 和 hard limit 仍要由你自己的应用或 API 流程处理。
| 用户动作 | Customer Portal 是否适合 | 建议落点 |
|---|---|---|
| 查看 pricing plan subscription | 适合只读展示 | Portal |
| 下载发票 | 可作为账单入口 | Portal 或自建账单页 |
| 更新付款方式 | 不适合作为承诺能力 | 自建页面 + Stripe API 流程 |
| 查看客户资料 | 适合只读展示 | Portal |
| 取消 advanced pricing plan subscription | 不适合作为承诺能力 | 自建页面 + API |
| Pro 升 Team | 不适合作为承诺能力 | 自建页面 + 版本迁移逻辑 |
| 设置本月超额上限 | Portal 不覆盖 | 产品数据库 + usage gate |
如果你的团队在多个国家协作，Stripe Dashboard、部署后台、队列监控和客户操作页经常分散在不同工作环境。计费重放、套餐迁移、信用额度补发这类动作要保留操作者、时间、request_id 和网络环境记录，并用Stripe Dashboard 稳定访问承载核心后台操作，避免客服和工程师查不到同一条账务链路。
Sandbox 和 availability 怎么验？
pricing plans 使用 /v2 API endpoints，官方文档要求用 sandboxes 测试，不能用传统 test mode。这个点很容易踩坑：你原来写给 sk_test_... 的集成测试，不能直接证明 /v2 pricing plan subscription 在 sandbox 里可用。
最小验证顺序如下：
- 在 Stripe Dashboard 确认 advanced usage-based billing private preview 权限。
- 创建 sandbox，重新建 meter、rate card、license fee、service action 和 pricing plan。
- 用 test cards 跑 Checkout 或 API subscription。
- 写入 test meter events，确认 upcoming invoice 或 preview invoice 的 line items。
- 模拟支付失败、取消服务、servicing paused、collection past_due 等事件。
- 把 webhook endpoint 切到 v2 Events 的处理方式，不要假设 payload 和老事件相同。
Stripe 文档列出 Checkout Session private preview 限制：最多 5 个 checkout_items，支付方式只覆盖 cards、Link、Apple Pay、Google Pay；不能指定 billing cycle anchor，不能用 discounts，不能用 Connect，不能加 optional items 或 cross-sells，也不能限制客户只有一个 subscription。
这些限制对 AI SaaS 很关键。比如你想在 Checkout 里卖 Pro 套餐再加一个 one-click credit pack，private preview 下的 optional items 和 cross-sells 就不能按成熟产品页来设计。
Meter events 要同步发还是进队列？
不要让用户生成内容的同步链路依赖 Stripe 成功返回。一次 AI 请求已经可能经过模型、对象存储、内容审核、回调和数据库写入，再把 Stripe 上报塞进主链路，任何 429 或 token 过期都会让用户误以为生成失败。
更稳的路径是 outbox：业务成功后先写本地不可变 usage_ledger，再写 meter_event_outbox。后台 worker 读取 outbox，带稳定 identifier 和 idempotency key 上报 Stripe。失败就退避重试，超过阈值进 dead letter。
| 事件量级 | 上报方式 | 关键控制 |
|---|---|---|
| < 10 events/sec | 同步或轻量 worker | identifier、idempotency key |
| 10-500 events/sec | Queue worker | 并发控制、退避重试、死信队列 |
| 500-1000 events/sec | 聚合后上报 | 按 request 或 customer 聚合 |
| > 1000 events/sec | 评估 Meter Event Stream | session token 刷新、429 告警、吞吐压测 |
Stripe 的 recording usage API 文档给出几个硬数字：标准 Meter Event endpoint 在 live mode 下是 1000 calls/sec；timestamp 最多回溯 35 个日历日，未来最多 5 分钟用于时钟漂移；usage value 是数值字段，可接受小数并体现在 invoice 上。
Meter Event Stream 属于 API v2 高吞吐路径。官方文档和 changelog 写到可发送 10,000 events/sec，更高限制要联系 sales；session token 是短期 token，文档口径是 15 分钟有效。不要把它当长期 secret 放进 CI。
数据库模型怎么落地？
Stripe 是账务事实源，不是你产品的唯一事实源。AI SaaS 仍要自己知道用户当前是否能继续生成、套餐显示什么、哪些事件已上报、哪些 credit 已经被产品侧消耗。
| 表 | 关键字段 | 用途 |
|---|---|---|
plans | plan_code, stripe_pricing_plan_id, version | 映射本地套餐和 Stripe pricing plan |
plan_entitlements | plan_code, meter_code, included_credit, overage_policy | 控制权限、展示和 hard limit |
usage_ledger | usage_id, customer_id, meter_code, raw_value, billable_value, request_id | 不可变用量流水 |
meter_event_outbox | usage_id, stripe_identifier, attempts, last_error, status | Stripe 上报队列 |
credit_ledger | credit_id, source, amount, expires_at, stripe_credit_grant_id | 产品额度和 Stripe credit grant 的桥 |
billing_reconciliation | period, meter_code, local_total, stripe_total, diff | 月结对账 |
usage_ledger 不要更新原始数值。修正用新的 adjustment 或 reversal 事件，保留旧行。客户问「为什么这个月多了 18 美元」时，你要能把 request_id、模型、原始 token、折算规则、Stripe identifier 和 invoice line 串起来。
最小 Pro 套餐可以这样落：
| 套餐 | License fee | Credits | Metered items | 超额规则 |
|---|---|---|---|---|
| Starter | $9/月 | $3 monthly credit | ai_tokens, image_generation | 不允许超额，余额不足提示升级 |
| Pro | $29/月 | $10 monthly credit | ai_tokens, image_generation, api_call | 允许超额，产品侧设置 $20 hard limit |
| Team | $99/月 | $50 monthly credit | ai_tokens, api_call, workflow_run | 允许超额 + invoice 支付 |
Starter 不允许超额，能减少早期客服压力。Pro 可以允许小额超额，但 hard limit 要在产品侧先拦截。Team 更像 B2B 账单，要处理 seat、采购联系人、税号、PO 和 invoice memo，不能只当个人订阅放大版。
Stripe Usage-Based Billing 不覆盖什么
没有拿到 private preview 权限的 Stripe 账户，可能看不到 pricing plans、rate cards 或相关 /v2 资源。本文只按官方公开文档和 changelog 写接入限制，不代表每个账户都能立即开通。
税务、Revenue Recognition、Connect、跨币种 credit、企业采购审批没有展开。Stripe 文档对 Checkout private preview 已明确 Connect 不可用，跨平台收款或 marketplace 模式不要套用这里的单商户模型。
价格表里的 $9/$29/$99 只是结构例子，不是定价建议。AI 模型成本、毛利、退款率和客服成本会变化，真正上线前要把单次任务毛利和用户可理解单位重新算一遍。