autumn-best-practices

Autumn 集成指南

始终查阅 docs.useautumn.com，获取代码示例和最新 API。

Autumn 是一款以 TypeScript 为先的计费 SDK，通过 Stripe 支持订阅、按用量定价、额度、试用等功能。

---

快速参考

环境变量

• AUTUMN_SECRET_KEY - API 密钥（必需）。请前往 app.useautumn.com 获取

安装

npm install autumn-js    # Node.js
pip install autumn-py    # Python

核心方法

方法	用途
customers.create	创建或获取客户（幂等）
checkout	获取 Stripe URL 或支付预览
attach	确认购买（使用已保存的银行卡）
cancel	取消订阅
check	验证功能访问权限
track	记录用量
products.list	获取包含计费场景的产品

---

核心配置选项

选项	说明
secretKey	必需。来自环境变量 AUTUMN_SECRET_KEY
baseURL	可选。默认为 https://api.useautumn.com

---

计费模式

检查 → 执行 → 记录

对于受保护的操作，始终遵循以下顺序：

const { data } = await autumn.check({ customer_id, feature_id: "api_calls" });
if (!data.allowed) return { error: "Limit reached" };

const result = await doWork();

await autumn.track({ customer_id, feature_id: "api_calls", value: 1 });
return result;

两步结账

const { data } = await autumn.checkout({ customer_id, product_id: "pro" });

if (data.url) return redirect(data.url);  // New customer → Stripe

// Returning customer → show confirmation, then:
await autumn.attach({ customer_id, product_id: "pro" });

---

产品场景

使用 products.list 获取场景。不要构建自定义逻辑。

场景	含义
new	尚未订阅
active	当前使用此套餐
scheduled	已安排在未来生效
upgrade	有更高级别的套餐可用
downgrade	有更低级别的套餐可用
renew	已取消，可重新激活

---

功能类型

类型	行为
boolean	授予或拒绝访问权限
metered	根据限额跟踪用量
credit_system	多个功能共用的额度池

---

React Hooks

Hook	用途
useCustomer	获取客户、结账、关联、检查
usePricingTable	获取包含场景的产品

import { AutumnProvider } from "autumn-js/react";

<AutumnProvider>{children}</AutumnProvider>

---

处理程序导入

框架	导入
Next.js	autumn-js/next
React Router	autumn-js/react-router
Hono	autumn-js/hono
Express	autumn-js/express
Fastify	autumn-js/fastify
通用	autumn-js/backend

---

常见注意事项

1. URL 字段 - 结账 URL 是 data.url，而不是 data.checkout_url
2. 前端检查 - 仅用于改善用户体验。始终在后端执行检查
3. 成功后记录 - 仅在操作完成后记录用量
4. 额度系统 - 跟踪按量计费的功能，而不是额度系统本身
5. 通过免费套餐取消 - 优先使用 attach({ product_id: "free" })，而不是 cancel()
6. 幂等创建 - 如果 ID 已存在，customers.create 会返回现有客户

---

资源

• 文档
• API 参考
• LLMs.txt
• GitHub