# Autumn Billing (/docs/plugins/autumn)

Autumn Billing 的 Better Auth 插件





[Autumn](https://useautumn.com) 是用于运行 SaaS 定价计划的开源基础设施。它位于您的应用程序和 Stripe 之间，作为客户订阅状态、用量计量和功能权限的数据库。

<Callout>
  该插件由 Autumn 团队维护。如有错误、问题或功能请求，
  请访问 [Autumn GitHub 仓库](https://github.com/useautumn/autumn)。
</Callout>

<Card href="https://discord.gg/STqxY92zuS" title="在 Autumn 的 Discord 上寻求帮助">
  我们在线随时为您解答任何问题。
</Card>

## 功能 [#功能]

* 一个函数即可处理所有结账、订阅和支付流程
* 无需 Webhook：向 Autumn 查询您需要的数据
* 管理应用程序的免费和付费计划
* 用于按用量计费和周期性限额的用量跟踪
* 通过 Autumn 仪表盘自定义计划和定价变更

<Steps>
  <Step>
    ### 设置 Autumn 账户 [#设置-autumn-账户]

    首先，在 Autumn 的[仪表盘](https://app.useautumn.com)中创建定价计划，在那里定义每个计划和产品可访问的内容以及计费方式。在此示例中，我们将为 AI 聊天机器人处理免费版和专业版计划，每月提供一定数量的 `messages`。
  </Step>

  <Step>
    ### 安装 Autumn SDK [#安装-autumn-sdk]

    <CodeBlockTabs defaultValue="npm" groupId="persist-install">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install autumn-js
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add autumn-js
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add autumn-js
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add autumn-js
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <Callout>
      如果您使用的是分离的客户端和服务器结构，请确保在项目的两个部分都安装该插件。
    </Callout>
  </Step>

  <Step>
    ### 将 `AUTUMN_SECRET_KEY` 添加到环境变量 [#将-autumn_secret_key-添加到环境变量]

    您可以在 Autumn 仪表盘的“[开发者](https://app.useautumn.com/sandbox/onboarding)”中找到它。

    ```bash title=".env"
    AUTUMN_SECRET_KEY=am_sk_xxxxxxxxxx
    ```
  </Step>

  <Step>
    ### 将 Autumn 插件添加到您的 `auth` 配置中 [#将-autumn-插件添加到您的-auth-配置中]

    <Tabs items="[&#x22;User&#x22;, &#x22;Organization&#x22;, &#x22;User & Organization&#x22;, &#x22;Custom&#x22;]">
      <Tab value="User">
        ```ts title="auth.ts"
        import { autumn } from "autumn-js/better-auth";

        export const auth = betterAuth({
          // ...
          plugins: [autumn()],
        });
        ```
      </Tab>

      <Tab value="Organization">
        ```ts title="auth.ts"
        import { autumn } from "autumn-js/better-auth";
        import { organization } from "better-auth/plugins";

        export const auth = betterAuth({
          // ...
          plugins: [organization(), autumn({ customerScope: "organization" })],
        });
        ```
      </Tab>

      <Tab value="User & Organization">
        ```ts title="auth.ts"
        import { autumn } from "autumn-js/better-auth";
        import { organization } from "better-auth/plugins";

        export const auth = betterAuth({
          // ...
          plugins: [
            organization(),
            autumn({ customerScope: "user_and_organization" })
          ],
        });
        ```
      </Tab>

      <Tab value="Custom">
        ```ts title="auth.ts"
        import { autumn } from "autumn-js/better-auth";
        import { organization } from "better-auth/plugins";

        export const auth = betterAuth({
          // ...
          plugins: [
            organization(),
            autumn({
              identify: async ({ session, organization }) => {
                return {
                  customerId: "your_customer_id",
                  customerData: {
                    name: "Customer Name",
                    email: "customer@gmail.com",
                  },
                };
              },
            }),
          ],
        });
        ```
      </Tab>
    </Tabs>

    <Callout>
      Autumn 会在客户注册时自动创建客户，并为其分配您创建的任何默认计划（例如免费版计划）。您可以选择哪些对象成为客户：个人用户、组织、两者，或工作区等自定义对象。
    </Callout>
  </Step>

  <Step>
    ### 添加 `<AutumnProvider />` [#添加-autumnprovider-]

    在布局文件中，使用 AutumnProvider 组件包裹您的应用程序，并将 `useBetterAuth` 设为 true。

    ```tsx title="app/layout.tsx"
    import { AutumnProvider } from "autumn-js/react";

    export default function RootLayout({
      children,
    }: {
      children: React.ReactNode;
    }) {
      return (
        <html>
          <body>
            <AutumnProvider useBetterAuth={true}>
              {children}
            </AutumnProvider>
          </body>
        </html>
      );
    }
    ```
  </Step>
</Steps>

## 使用方法 [#使用方法]

### 处理支付 [#处理支付]

当客户想购买专业版时，调用 `attach` 函数将客户重定向到 Stripe 结账页面。

如果客户已有支付方式，`AttachDialog` 会打开，方便客户确认订阅或购买，并处理支付。

<Callout type="warn">
  {" "}

  请确保已在 [Autumn
  仪表盘](https://app.useautumn.com/integrations/stripe)中粘贴您的 [Stripe 测试密钥
  ](https://dashboard.stripe.com/test/apikeys)。
</Callout>

```tsx
import { useCustomer, AttachDialog } from "autumn-js/react";

export default function PurchaseButton() {
  const { attach } = useCustomer();

  return (
    <button
      onClick={async () => {
        await attach({
          productId: "pro",
          dialog: AttachDialog,
        });
      }}
    >
      升级到专业版
    </button>
  );
}
```

AttachDialog 组件可以直接从 `autumn-js/react` 库中使用（如上例所示），也可以下载作为 [shadcn/ui 组件](https://docs.useautumn.com/quickstart/shadcn) 进行自定义。

### 集成定价逻辑 [#集成定价逻辑]

通过以下函数集成您的客户端和服务器端定价层逻辑：

* `check`：检查客户是否 `allowed` 发送消息。
* `track`：在 Autumn 中跟踪用量事件（通常在服务器端执行）
* `customer`：在您的 UI 中显示相关计费数据（订阅、功能余额）

在服务器端，您可以通过 `auth` 对象访问 Autumn 的函数。

<Tabs items="[&#x22;Client&#x22;, &#x22;Server&#x22;]">
  <Tab value="Client">
    ```jsx
    import { useCustomer } from "autumn-js/react";

    export default function SendChatMessage() {
      const { customer, allowed, refetch } = useCustomer();

      return (
        <>
          <button
            onClick={async () => {
              if (allowed({ featureId: "messages" })) {
                //... send chatbot message server-side, then
                await refetch(); // refetch customer usage data
                alert(
                  "Remaining messages: " + customer?.features.messages?.balance
                );
              } else {
                alert("You're out of messages");
              }
            }}
          >
            Send Message
          </button>
        </>
      );
    }
    ```
  </Tab>

  <Tab value="Server">
    ```typescript Server
    import { auth } from "@/lib/auth";

    // check on the backend if the customer can send a message
    const { allowed } = await auth.api.check({
      headers: await headers(), // pass the request headers
      body: {
        featureId: "messages",
      },
    });

    // server-side function to send the message

    // then track the usage
    await auth.api.track({
      headers: await headers(),
      body: {
        featureId: "messages",
        value: 2,
      },
    });
    ```
  </Tab>
</Tabs>

### 其他功能 [#其他功能]

#### openBillingPortal() [#openbillingportal]

打开计费门户，客户可更新支付方式或取消计划。

```tsx
import { useCustomer } from "autumn-js/react";

export default function BillingSettings() {
  const { openBillingPortal } = useCustomer();

  return (
    <button
      onClick={async () => {
        await openBillingPortal({
          returnUrl: "/settings/billing",
        });
      }}
    >
      管理计费
    </button>
  );
}
```

#### cancel() [#cancel]

取消产品或订阅。

```tsx
import { useCustomer } from "autumn-js/react";

export default function CancelSubscription() {
  const { cancel } = useCustomer();

  return (
    <button
      onClick={async () => {
        await cancel({ productId: "pro" });
      }}
    >
      取消订阅
    </button>
  );
}
```

#### 获取发票历史记录 [#获取发票历史记录]

向 `useCustomer` 传入 `expand` 参数以获取更多信息。您可以展开 `invoices`、`trials_used`、`payment_method` 或 `rewards`。

```tsx
import { useCustomer } from "autumn-js/react";

export default function CustomerProfile() {
  const { customer } = useCustomer({ expand: ["invoices"] });

  return (
    <div>
      <h2>客户档案</h2>
      <p>姓名: {customer?.name}</p>
      <p>邮箱: {customer?.email}</p>
      <p>余额: {customer?.features.chat_messages?.balance}</p>
    </div>
  );
}
```