Laravel + Cashier 订阅计费完整链路：SaaS

Laravel Cashier 是需自主设计链路的计费工具包，非开箱即用SaaS系统；多价格订阅须全用price_id、属同一product；addPrice/addMeteredPrice生效时机影响账期；cancel()不立即停服，需cancelNow()；业务权限校验不可依赖ends_at。

直接说结论：Laravel Cashier 不是“开箱即用”的 SaaS 订阅系统，而是一套需要你主动设计链路、补全边界逻辑的计费工具包。它帮你省掉 Stripe Webhook 解析、发票生成、订阅状态同步等样板代码，但不会替你决定“用户升级时要不要保留旧服务”“计量用量怎么防刷”“试用期结束前要不要发提醒邮件”。

创建多价格订阅时，newSubscription 的数组参数必须全是 Stripe 价格 ID（price_xxx），不能混用 plan ID

常见错误是把老版 Stripe Plan ID（如 plan_ght23）和新版 Price ID（price_1Qx...z）一起传给 newSubscription，结果抛出 Invalid price id 或静默失败。

• Stripe Dashboard 中所有新创建的价格都以 price_ 开头；Plan ID 已被弃用，Cashier 12+ 完全不支持
• 多价格订阅本质是「一个 subscription 对应多个 active price items」，不是多个 plan 的叠加
• 如果想实现“基础版 + API 配额包 + 协作空间包”，就该在 Stripe 创建三个独立的 recurring 类型 price，并在 Laravel 侧用 ['price_basic', 'price_api', 'price_collab'] 传入
• 注意：Cashier 不会校验这些 price 是否属于同一产品（product），但 Stripe 后台要求它们必须归属同一个 product 才能共存于一个 subscription

addPrice 和 addMeteredPrice 的触发时机影响账单周期与用量归属

往已有订阅里加价，不是“立刻生效”，而是取决于 price 的 billing scheme 和 anchor date 设置。尤其对计量计费（metered）价格，错误调用会导致用量被记到错误账期。

• addPrice('price_id') 默认在下一个 billing cycle 生效；若要立即生效，需显式传参：->addPrice('price_id', ['prorate' => true])
• addMeteredPrice 只是注册一个 metered item，不产生账单；真正计费依赖后续调用 reportUsage，且 reportUsage 必须指定 timestamp —— 如果漏传或传错，Stripe 会按当前时间归入最近 billing period，导致用量错乱
• 典型坑：用户在 7 月 15 日开通 metered 服务，但直到 8 月 2 日才第一次 reportUsage；若没传 timestamp，Stripe 会把全部用量算进 8 月账单，而非从 7 月 15 日起分摊

取消订阅后，ends_at 字段不等于“服务终止时间”，真正的截止由 cancel_at_period_end 控制

很多开发者以为调用 $subscription->cancel() 就立刻停服，结果发现用户还能继续用到月底——这是因为 Cashier 默认使用 cancel_at_period_end=true 行为，符合 Stripe 的安全设计，但业务上常需干预。

• $subscription->cancel() 等价于 Stripe 的 cancel_at_period_end: true，只改 ends_at，不改服务状态
• 要立即停服，必须用：$subscription->cancelNow()（对应 Stripe 的 cancel_now: true），此时 ends_at 会被设为当前时间，且 Stripe 会立即关闭 access
• 关键细节：即使调用了 cancelNow()，已生成但未支付的 invoice（比如当月 prorated 账单）仍会留在 Stripe 后台，需手动 void 或 mark as paid，否则影响财务对账

最易被忽略的点是：Cashier 不管理「业务侧服务开关」。它只同步 Stripe 的 subscription 状态，而你的应用是否允许用户访问高级功能，必须在 middleware 或 policy 中显式检查 $user->subscribed('main') 或 $user->subscription('main')->hasPrice('price_pro')，不能只依赖数据库里的 ends_at 值做判断——因为 Stripe 状态可能延迟同步，Webhook 处理失败时就会脱钩。