用途:为软件应用构建账单页面,让客户更改套餐、取消订阅并查看用量。使用前需在项目根目录存在 autumn.config.ts 配置;若不存在,运行 npx atmn init 登录并生成该文件。
集成路径:若代码库已有 AutumnProvider 与 autumnHandler 挂载,走 React 路径;若仅初始化了 Autumn 客户端,走后端 SDK 路径。实现前应先告知用户所选路径。
主要能力:
- 活跃套餐:通过 customer.subscriptions 与 purchases 展示当前订阅与一次性购买,可按 status === "active" 过滤。
- 用量余额:计量功能含 granted、usage、remaining 字段,可显示剩余/已授予;追踪用量或变更套餐后调用 refetch() 更新。
- 客户资格:传入 customerId 后每个套餐带 customerEligibility,含 attachAction(activate、upgrade、downgrade、purchase、none)、status(active、scheduled 或未定义)与 trialAvailable,用于定价页按钮文案。React 的 useListPlans 会自动带上客户上下文。
- 切换套餐:使用 attach 处理升级、降级与新订阅;后端返回 paymentUrl 时需重定向。
- 取消与恢复:通过 billing.update 配合 cancelAction,取值为 cancel_end_of_cycle 或 uncancel;当 canceledAt 非空且订阅仍活跃时可反悔。
- Stripe 账单门户:需先在 Stripe 设置中启用,再调用 openCustomerPortal 并传入 returnUrl。
- 用量历史:events.aggregate 提供聚合时间序列,可传给 Recharts 等图表库,支持 range 如 30d。
- 预付加购:通过 attach 传 planId 和 options(featureId、quantity)购买一次性套餐。
使用方式:提供 React、TypeScript 与 Python 三套调用形式,React 使用 autumn-js/react 的 useCustomer、useListPlans、useAggregateEvents 等 hook;后端使用 autumn-js 或 autumn_sdk 的 customers、plans、billing、events 方法,需提供 customerId,密钥形如 am_sk_test_xxx。
限制:以上升级、降级、续订与恢复均由 Autumn 自动处理;套餐 ID 来自 Autumn 配置;本次资料未提供收费、价格或平台细节。