autumn-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Autumn Integration Guide

Autumn集成指南

Always consult docs.useautumn.com for code examples and latest API.

Autumn is a TypeScript-first billing SDK supporting subscriptions, usage-based pricing, credits, trials, and more via Stripe.

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

Autumn是优先支持TypeScript的计费SDK，通过Stripe支持订阅、按使用量定价、积分、试用等多种功能。

Quick Reference

快速参考

Environment Variables

环境变量

```
AUTUMN_SECRET_KEY
```
- API key (required). Get one at app.useautumn.com

```
AUTUMN_SECRET_KEY
```
- API密钥（必填）。可在app.useautumn.com获取。

Installation

安装

bash

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

bash

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

Core Methods

核心方法

Method	Purpose
`customers.create`	Create or get customer (idempotent)
`checkout`	Get Stripe URL or payment preview
`attach`	Confirm purchase (card on file)
`cancel`	Cancel subscription
`check`	Verify feature access
`track`	Record usage
`products.list`	Get products with billing scenarios

方法	用途
`customers.create`	创建或获取客户（幂等操作）
`checkout`	获取Stripe支付链接或支付预览
`attach`	确认购买（绑定卡片）
`cancel`	取消订阅
`check`	验证功能访问权限
`track`	记录使用量
`products.list`	获取包含计费场景的产品列表

Core Config Options

核心配置选项

Option	Notes
`secretKey`	Required. From env `AUTUMN_SECRET_KEY`
`baseURL`	Optional. Defaults to `https://api.useautumn.com`

选项	说明
`secretKey`	必填，从环境变量 `AUTUMN_SECRET_KEY` 读取
`baseURL`	可选，默认值为 `https://api.useautumn.com`

Billing Patterns

计费模式

Check → Work → Track

检查 → 执行操作 → 上报用量

Always follow this order for protected actions:

typescript

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;

对于受保护的操作请始终遵循这个顺序：

typescript

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;

Two-Step Checkout

两步结账流程

typescript

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" });

typescript

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

if (data.url) return redirect(data.url);  // 新客户 → 跳转Stripe

// 老客户 → 展示确认页，然后执行：
await autumn.attach({ customer_id, product_id: "pro" });

Product Scenarios

产品场景

Use

products.list

to get scenarios. Don't build custom logic.

Scenario	Meaning
`new`	Not subscribed
`active`	Currently on plan
`scheduled`	Scheduled for future
`upgrade`	Higher tier available
`downgrade`	Lower tier available
`renew`	Cancelled, can reactivate

使用

products.list

获取场景，不要自行编写自定义逻辑。

场景	含义
`new`	未订阅
`active`	当前订阅生效中
`scheduled`	订阅已排期，未来生效
`upgrade`	可升级到更高档位
`downgrade`	可降级到更低档位
`renew`	已取消，可重新激活

Feature Types

功能类型

Type	Behavior
`boolean`	Access granted or denied
`metered`	Usage tracked against limit
`credit_system`	Pool for multiple features

类型	行为
`boolean`	允许或拒绝访问
`metered`	按使用量限制，跟踪用量
`credit_system`	支持多个功能共享的积分池

React Hooks

Hook	Purpose
`useCustomer`	Get customer, checkout, attach, check
`usePricingTable`	Get products with scenarios

tsx

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

<AutumnProvider>{children}</AutumnProvider>

Hook	用途
`useCustomer`	获取客户信息、结账、绑定支付方式、权限检查
`usePricingTable`	获取包含场景的产品列表

tsx

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

<AutumnProvider>{children}</AutumnProvider>

Handler Imports

处理器导入

Framework	Import
Next.js	`autumn-js/next`
React Router	`autumn-js/react-router`
Hono	`autumn-js/hono`
Express	`autumn-js/express`
Fastify	`autumn-js/fastify`
Generic	`autumn-js/backend`

框架	导入路径
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`

Common Gotchas

常见注意事项

URL field - Checkout URL is
```
data.url
```
, not
```
data.checkout_url
```
Frontend checks - For UX only. Always enforce on backend
Track after success - Only track usage after work completes
Credit systems - Track metered features, not the credit system itself
Cancel via free plan - Prefer
```
attach({ product_id: "free" })
```
over
```
cancel()
```
Idempotent creation -
```
customers.create
```
returns existing customer if ID exists

URL字段 - 结账链接是
```
data.url
```
，不是
```
data.checkout_url
```
前端权限检查 - 仅用于优化用户体验，必须在后端再次校验
成功后再上报用量 - 仅在操作执行完成后上报使用量
积分系统 - 只需上报计量类功能的用量，无需上报积分系统本身的用量
通过免费套餐取消订阅 - 优先使用
```
attach({ product_id: "free" })
```
而非
```
cancel()
```
幂等创建 - 如果客户ID已存在，
```
customers.create
```
会返回已有的客户信息

autumn-best-practices

Original

Translation

Autumn Integration Guide

Autumn集成指南

Quick Reference

快速参考

Environment Variables

环境变量

Installation

安装

Core Methods

核心方法

Core Config Options

核心配置选项

Billing Patterns

计费模式

Check → Work → Track

检查 → 执行操作 → 上报用量

Two-Step Checkout

两步结账流程

Product Scenarios

产品场景

Feature Types

功能类型

React Hooks

React Hooks

Handler Imports

处理器导入

Common Gotchas

常见注意事项

Resources

资源