> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useautumn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup and payments

> Implement your app's payments and pricing model

In this example we'll create the pricing for a premium AI chatbot. We're going to have:

* A <Badge color="green">Free</Badge> plan that gives users 5 chat messages per month for free
* A <Badge color="blue">Pro</Badge> plan that gives users 100 chat messages per month for \$20 per month.

<View title="React hooks" icon="react">
  <Info>
    Autumn's client-side [hooks](/react/hooks/useCustomer) are supported for
    fullstack TypeScript apps. Please use the Server SDK for other frameworks.
  </Info>

  <Steps>
    <Step>
      ### Create your pricing plans

      Create a plan for each pricing tier that your app offers. In our example we'll create a "Free" and "Pro" plan, and assign them features.

      <Tip>
        Browse our [Examples](/examples) for guides on setting up credit systems, top ups and other common pricing models.
      </Tip>

      <Tabs>
        <Tab title="CLI">
          Run the following command in your root directory:

          <CodeGroup>
            ```bash bun theme={null}
            bunx atmn init
            ```

            ```bash npm theme={null}
            npx atmn init
            ```

            ```bash pnpm theme={null}
            pnpm dlx atmn init
            ```
          </CodeGroup>

          This will prompt you to login or create an account, and create an `autumn.config.ts` file. Paste in the code below, or view our [config schema](/cli/config) to build your own.

          ```typescript autumn.config.ts [expandable] theme={null}
          import { feature, item, plan } from "atmn";

          // Features
          export const messages = feature({
            id: "messages",
            name: "Messages",
            type: "metered",
            consumable: true,
          });

          // Plans
          export const free = plan({
            id: "free",
            name: "Free",
            autoEnable: true,
            items: [
              // 5 messages per month
              item({
                featureId: messages.id,
                included: 5,
                reset: { interval: "month" },
              }),
            ],
          });

          export const pro = plan({
            id: "pro",
            name: "Pro",
            price: {
              amount: 20,
              interval: "month",
            },
            items: [
              // 100 messages per month
              item({
                featureId: messages.id,
                included: 100,
                reset: { interval: "month" },
              }),
            ],
          });
          ```

          Then, push your changes to Autumn's sandbox environment.

          <CodeGroup>
            ```bash bun theme={null}
            bunx atmn push
            ```

            ```bash npm theme={null}
            npx atmn push
            ```

            ```bash pnpm theme={null}
            pnpm dlx atmn push
            ```
          </CodeGroup>

          <Tip>
            If you already have products created in the dashboard, run `atmn pull` to
            pull them into your local config.
          </Tip>
        </Tab>

        <Tab title="Dashboard">
          Create your [Autumn account](https://app.useautumn.com/), and the Free and Pro plans in the [Plans](https://app.useautumn.com/products) tab.

          <AccordionGroup>
            <Accordion title="Free Plan">
              * On the [Plans](https://app.useautumn.com/products) page, click **Create Plan**.
              * Name the plan (eg, "Free") and select plan type `Free`
              * Toggle the `auto-enable` flag, so that the plan is assigned whenever customers are created
              * In the plan editor, click **Add Feature to Plan**, and create a `Metered`, `Consumable` feature for "messages"
              * Configure the plan to grant `5` messages, and set the interval to `per month`
              * Click **Save**

              <Frame hint="Your Free plan should look like this">
                <img className="block dark:hidden" src="https://mintcdn.com/autumn-b9b4c0fb/df8oGyhsA_ngL7c4/assets/getting-started/free-plan-light.png?fit=max&auto=format&n=df8oGyhsA_ngL7c4&q=85&s=40b1906694ed200d91ddfbd9b972c294" width="1476" height="1284" data-path="assets/getting-started/free-plan-light.png" />

                <img className="hidden dark:block" src="https://mintcdn.com/autumn-b9b4c0fb/df8oGyhsA_ngL7c4/assets/getting-started/free-plan-dark.png?fit=max&auto=format&n=df8oGyhsA_ngL7c4&q=85&s=2eab7a285e28f85e188136ae2308ecee" width="1468" height="1266" data-path="assets/getting-started/free-plan-dark.png" />
              </Frame>
            </Accordion>

            <Accordion title="Pro Plan">
              * On the [Plans](https://app.useautumn.com/products) page, click **Create Plan**.
              * Name the plan (eg, "Pro") and select plan type `Paid`, `Recurring`, and set the price to `$20` per month
              * In the plan editor, click **Add Feature to Plan**, and add the `messages` feature that you created in the Free plan
              * Configure the plan to grant `100` messages, and set the interval to `per month`
              * Click **Save**

              <Frame hint="Your Pro plan should look like this">
                <img className="block dark:hidden" src="https://mintcdn.com/autumn-b9b4c0fb/df8oGyhsA_ngL7c4/assets/getting-started/pro-plan-light.png?fit=max&auto=format&n=df8oGyhsA_ngL7c4&q=85&s=729fd52cd39deab4741ea88f90917e2f" width="1448" height="1338" data-path="assets/getting-started/pro-plan-light.png" />

                <img className="hidden dark:block" src="https://mintcdn.com/autumn-b9b4c0fb/df8oGyhsA_ngL7c4/assets/getting-started/pro-plan-dark.png?fit=max&auto=format&n=df8oGyhsA_ngL7c4&q=85&s=7a27b31f42870bfdd8aed3f87084ae28" width="1452" height="1344" data-path="assets/getting-started/pro-plan-dark.png" />
              </Frame>
            </Accordion>
          </AccordionGroup>
        </Tab>
      </Tabs>
    </Step>

    <Step>
      ### Installation

      [Create an Autumn Secret key](https://app.useautumn.com/sandbox/dev?tab=api_keys), and paste it in your `.env` variables. Then, install the Autumn SDK. If you're using the CLI, this will be done for you.

      ```bash .env theme={null}
      AUTUMN_SECRET_KEY=am_sk_test_42424242...
      ```

      <CodeGroup>
        ```bash bun theme={null}
        bun add autumn-js
        ```

        ```bash npm theme={null}
        npm install autumn-js
        ```

        ```bash pnpm theme={null}
        pnpm add autumn-js
        ```

        ```bash yarn theme={null}
        yarn add autumn-js
        ```
      </CodeGroup>

      <Note>
        If you're using a separate backend and frontend, make sure to install the
        library in both.
      </Note>
    </Step>

    <Step>
      ### Add Endpoints Server-side

      Server-side, mount the Autumn handler. This will create endpoints in the `/api/autumn/*` path, which will be called by Autumn's frontend React hooks. These endpoints in turn call Autumn's API.

      The handler takes in an `identify` function where you should pass in the user ID or organization ID from your auth provider.

      <CodeGroup>
        ```typescript Next.js theme={null}
        // app/api/autumn/[...all]/route.ts

        import { autumnHandler } from "autumn-js/next";
        import { auth } from "@/lib/auth";

        export const { GET, POST } = autumnHandler({
            identify: async (request) => {
                // get the user from your auth provider (example: better-auth)
                const session = await auth.api.getSession({
                    headers: request.headers,
                });

                return {
                    customerId: session?.user.id, // or org ID
                    customerData: {
                        name: session?.user.name,
                        email: session?.user.email,
                    },
                };
            },
        });
        ```

        ```typescript Hono theme={null}
        // index.ts

        import { autumnHandler } from "autumn-js/hono";

        app.use(
            "/api/autumn/*",
            autumnHandler({
                identify: async (c: Context) => {
                    // get the user from your auth provider (example: better-auth)
                    const session = await auth.api.getSession({
                        headers: c.req.raw.headers,
                    });

                    return {
                        customerId: session?.user.id,
                        customerData: {
                            name: session?.user.name,
                            email: session?.user.email,
                        },
                    };
                },
            }),
        );
        ```

        ```typescript Express theme={null}
        import express from "express";
        import { autumnHandler } from "autumn-js/express";

        const app = express();

        // Body parser is required before the Autumn handler
        app.use(express.json());
        app.use(
          "/api/autumn",
          autumnHandler({
            identify: async (req) => {
              // get the user from your auth provider (example: better-auth)
              const session = await auth.api.getSession({
                headers: req.headers,
              });

              return {
                customerId: session?.user.id,
                customerData: {
                  name: session?.user.name,
                  email: session?.user.email,
                },
              };
            },
          }),
        );
        ```

        ```typescript Web Standard (Elysia, CF Workers, etc...) theme={null}
        // Works with any fetch()-compatible WinterTC environment
        import { autumnHandler } from "autumn-js/fetch";
        import { Elysia } from "elysia";

        const app = new Elysia()
          .mount(
            autumnHandler({
              identify: async (request) => {
                // get the user from your auth provider (example: better-auth)
                const session = await auth.api.getSession({
                  headers: request.headers,
                });

                return {
                  customerId: session?.user.id,
                  customerData: {
                    name: session?.user.name,
                    email: session?.user.email,
                  },
                };
              },
            }),
          )
          .listen(3002);
        ```

        ```typescript General (framework-agnostic) theme={null}
        // For any framework not listed above

        import { autumnHandler } from "autumn-js/backend";

        // Call this from your route handler
        const result = await autumnHandler({
            request: {
                url: request.url, // Full URL or path (e.g., "/api/autumn/customer")
                method: request.method,
                body: await request.json(),
            },
            customerId: session?.user.id,
            customerData: {
                name: session?.user.name,
                email: session?.user.email,
            },
        });

        // Return the response
        return new Response(JSON.stringify(result.response), {
            status: result.statusCode,
            headers: { "Content-Type": "application/json" },
        });
        ```
      </CodeGroup>

      <Check>
        Autumn's customer ID is the same as your internal user or org ID generated
        from your auth provider. No need to store any extra IDs.
      </Check>
    </Step>

    <Step>
      ### Add Provider Client-side

      Client side, wrap your application with the `<AutumnProvider>` component.

      ```jsx theme={null}
      // layout.tsx
      import { AutumnProvider } from "autumn-js/react";

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

    <Step>
      ### Create an Autumn customer

      From a frontend component, use the [`useCustomer()` hook](/react/hooks/useCustomer). This will automatically create an Autumn customer if they're a new user and enable the <Badge color="green">Free</Badge> plan for them, or get the customer's state for existing users.

      ```jsx React theme={null}
      import { useCustomer } from "autumn-js/react";

      const App = () => {
          const { data } = useCustomer();

          console.log("Autumn customer:", data);

          return <h1>My very profitable app</h1>;
      };
      ```

      <Expandable title="data object">
        ```json expandable theme={null}
        {
            "id": "user_123",
            "createdAt": 1764932560414,
            "name": "My First Customer",
            "email": null,
            "fingerprint": null,
            "stripeId": null,
            "env": "sandbox",
            "metadata": {},
            "sendEmailReceipts": false,
            "subscriptions": [
                {
                    "planId": "free",
                    "autoEnable": true,
                    "addOn": false,
                    "status": "active",
                    "pastDue": false,
                    "canceledAt": null,
                    "expiresAt": null,
                    "trialEndsAt": null,
                    "startedAt": 1764932560519,
                    "currentPeriodStart": null,
                    "currentPeriodEnd": null,
                    "quantity": 1
                }
            ],
            "purchases": [],
            "balances": {
                "messages": {
                    "featureId": "messages",
                    "granted": 5,
                    "remaining": 5,
                    "usage": 0,
                    "unlimited": false,
                    "overageAllowed": false,
                    "maxPurchase": null,
                    "nextResetAt": 1767610960519
                }
            }
        }
        ```
      </Expandable>

      You will see your user under the [customers](https://app.useautumn.com/customers) page in the Autumn dashboard.
    </Step>

    <Step>
      ### Stripe Payment Flow

      Call `attach` when the customer wants to purchase the <Badge color="blue">Pro</Badge> plan. This will return a Stripe payment URL. Once they've paid, Autumn will grant access to "100 messages per month" defined in Step 1.

      <Note>
        Use Stripe's test card `4242 4242 4242 4242` to make a purchase in sandbox.
        You can enter any Expiry and CVV.
      </Note>

      ```jsx React theme={null}
      import { useCustomer } from "autumn-js/react";

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

          return (
              <button
                  onClick={async () => {
                      await attach({
                          planId: "pro",
                          redirectMode: "always",
                      });
                  }}
              >
                  Select Pro Plan
              </button>
          );
      }
      ```

      This will handle any plan changes scenario (upgrades, downgrades, one-time topups, renewals, etc).

      Upgrades will happen immediately, and downgrades will be scheduled for the next billing cycle.

      <Note>
        The **`redirectMode: "always"`** flag will always return a payment URL.

        New purchases redirect to Stripe Checkout to enter payment details, and subsequent charges redirect to an Autumn hosted, one-click confirmation page.

        You can build your own billing confirmation flows by using the [previewAttach](/api-reference/billing/previewAttach) function.
      </Note>
    </Step>
  </Steps>
</View>

<View title="Server SDK" icon="server">
  <Steps>
    <Step>
      ### Create your pricing plans

      Create a plan for each pricing tier that your app offers. In our example we'll create a "Free" and "Pro" plan, and assign them features.

      <Tip>
        Browse our [Examples](/examples) for guides on setting up credit systems, top ups and other common pricing models.
      </Tip>

      <Tabs>
        <Tab title="CLI">
          Run the following command in your root directory:

          <CodeGroup>
            ```bash bun theme={null}
            bunx atmn init
            ```

            ```bash npm theme={null}
            npx atmn init
            ```

            ```bash pnpm theme={null}
            pnpm dlx atmn init
            ```
          </CodeGroup>

          This will prompt you to login or create an account, and create an `autumn.config.ts` file. Paste in the code below, or view our [config schema](/cli/config) to build your own.

          ```typescript autumn.config.ts [expandable] theme={null}
          import { feature, item, plan } from "atmn";

          // Features
          export const messages = feature({
            id: "messages",
            name: "Messages",
            type: "metered",
            consumable: true,
          });

          // Plans
          export const free = plan({
            id: "free",
            name: "Free",
            autoEnable: true,
            items: [
              // 5 messages per month
              item({
                featureId: messages.id,
                included: 5,
                reset: { interval: "month" },
              }),
            ],
          });

          export const pro = plan({
            id: "pro",
            name: "Pro",
            price: {
              amount: 20,
              interval: "month",
            },
            items: [
              // 100 messages per month
              item({
                featureId: messages.id,
                included: 100,
                reset: { interval: "month" },
              }),
            ],
          });
          ```

          Then, push your changes to Autumn's sandbox environment.

          <CodeGroup>
            ```bash bun theme={null}
            bunx atmn push
            ```

            ```bash npm theme={null}
            npx atmn push
            ```

            ```bash pnpm theme={null}
            pnpm dlx atmn push
            ```
          </CodeGroup>

          <Tip>
            If you already have products created in the dashboard, run `atmn pull` to
            pull them into your local config.
          </Tip>
        </Tab>

        <Tab title="Dashboard">
          Create your [Autumn account](https://app.useautumn.com/), and the Free and Pro plans in the [Plans](https://app.useautumn.com/products) tab.

          <AccordionGroup>
            <Accordion title="Free Plan">
              * On the [Plans](https://app.useautumn.com/products) page, click **Create Plan**.
              * Name the plan (eg, "Free") and select plan type `Free`
              * Toggle the `auto-enable` flag, so that the plan is assigned whenever customers are created
              * In the plan editor, click **Add Feature to Plan**, and create a `Metered`, `Consumable` feature for "messages"
              * Configure the plan to grant `5` messages, and set the interval to `per month`
              * Click **Save**

              <Frame hint="Your Free plan should look like this">
                <img className="block dark:hidden" src="https://mintcdn.com/autumn-b9b4c0fb/df8oGyhsA_ngL7c4/assets/getting-started/free-plan-light.png?fit=max&auto=format&n=df8oGyhsA_ngL7c4&q=85&s=40b1906694ed200d91ddfbd9b972c294" width="1476" height="1284" data-path="assets/getting-started/free-plan-light.png" />

                <img className="hidden dark:block" src="https://mintcdn.com/autumn-b9b4c0fb/df8oGyhsA_ngL7c4/assets/getting-started/free-plan-dark.png?fit=max&auto=format&n=df8oGyhsA_ngL7c4&q=85&s=2eab7a285e28f85e188136ae2308ecee" width="1468" height="1266" data-path="assets/getting-started/free-plan-dark.png" />
              </Frame>
            </Accordion>

            <Accordion title="Pro Plan">
              * On the [Plans](https://app.useautumn.com/products) page, click **Create Plan**.
              * Name the plan (eg, "Pro") and select plan type `Paid`, `Recurring`, and set the price to `$20` per month
              * In the plan editor, click **Add Feature to Plan**, and add the `messages` feature that you created in the Free plan
              * Configure the plan to grant `100` messages, and set the interval to `per month`
              * Click **Save**

              <Frame hint="Your Pro plan should look like this">
                <img className="block dark:hidden" src="https://mintcdn.com/autumn-b9b4c0fb/df8oGyhsA_ngL7c4/assets/getting-started/pro-plan-light.png?fit=max&auto=format&n=df8oGyhsA_ngL7c4&q=85&s=729fd52cd39deab4741ea88f90917e2f" width="1448" height="1338" data-path="assets/getting-started/pro-plan-light.png" />

                <img className="hidden dark:block" src="https://mintcdn.com/autumn-b9b4c0fb/df8oGyhsA_ngL7c4/assets/getting-started/pro-plan-dark.png?fit=max&auto=format&n=df8oGyhsA_ngL7c4&q=85&s=7a27b31f42870bfdd8aed3f87084ae28" width="1452" height="1344" data-path="assets/getting-started/pro-plan-dark.png" />
              </Frame>
            </Accordion>
          </AccordionGroup>
        </Tab>
      </Tabs>
    </Step>

    <Step>
      ### Installation

      [Create an Autumn Secret key](https://app.useautumn.com/sandbox/dev?tab=api_keys), and paste it in your `.env` variables. Then, install the Autumn SDK. If you're using the CLI, this will be done for you.

      ```bash .env theme={null}
      AUTUMN_SECRET_KEY=am_sk_test_42424242...
      ```

      <CodeGroup>
        ```bash bun theme={null}
        bun add autumn-js
        ```

        ```bash npm theme={null}
        npm install autumn-js
        ```

        ```bash pnpm theme={null}
        pnpm add autumn-js
        ```

        ```bash yarn theme={null}
        yarn add autumn-js
        ```

        ```bash pip theme={null}
        pip install autumn-sdk
        ```
      </CodeGroup>
    </Step>

    <Step>
      ### Create an Autumn customer

      When the customer signs up, create an Autumn customer for them. Autumn will automatically enable the <Badge color="green">Free</Badge> plan, since you marked it with the `auto-enable` flag.

      <CodeGroup>
        ```typescript TypeScript theme={null}
        import { Autumn } from "autumn-js";

        const autumn = new Autumn({
            secretKey: "am_sk_42424242",
        });

        const customer = await autumn.customers.getOrCreate({
            customerId: "user_or_org_id_from_auth",
            name: "John Doe",
            email: "john@example.com",
        });
        ```

        ```python Python theme={null}
        import asyncio
        from autumn_sdk import Autumn

        autumn = Autumn('am_sk_42424242')

        async def main():
            customer = await autumn.customers.get_or_create(
                customer_id="user_or_org_id_from_auth",
                name="John Doe",
                email="john@example.com",
            )

        asyncio.run(main())
        ```

        ```bash cURL theme={null}
        curl --request POST \
          --url https://api.useautumn.com/v1/customers \
          --header 'Authorization: Bearer am_sk_42424242' \
          --header 'Content-Type: application/json' \
          --data '{
          "customer_id": "user_or_org_id_from_auth",
          "name": "John Doe",
          "email": "john@example.com"
        }'
        ```
      </CodeGroup>

      <Check>
        Autumn's customer ID is the same as your internal user or org ID generated
        from your auth provider. No need to store any extra IDs.
      </Check>

      In the Autumn dashboard, you will see your user under the [customers](https://app.useautumn.com/customers) page.
    </Step>

    <Step>
      ### Stripe Payment Flow

      Call `attach` when the customer wants to purchase the <Badge color="blue">Pro</Badge> plan. This will return a Stripe payment URL. Once they've paid, Autumn will grant access to "100 messages per month" defined in Step 1.

      <CodeGroup>
        ```typescript TypeScript theme={null}
        import { Autumn } from "autumn-js";

        const autumn = new Autumn({
            secretKey: "am_sk_42424242",
        });

        const response = await autumn.billing.attach({
            customerId: "user_or_org_id_from_auth",
            planId: "pro",
            redirectMode: "always",
        });

        // Redirect customer to complete payment or confirm plan change
        redirect(response.paymentUrl);
        ```

        ```python Python theme={null}
        import asyncio
        from autumn_sdk import Autumn

        autumn = Autumn('am_sk_42424242')

        async def main():
          response = await autumn.billing.attach(
              customer_id='user_or_org_id_from_auth',
              plan_id='pro',
              redirect_mode='always',
          )

        asyncio.run(main())
        ```

        ```bash cURL theme={null}
        curl -X POST 'https://api.useautumn.com/v1/attach' \
        -H 'Authorization: Bearer am_sk_42424242' \
        -H 'Content-Type: application/json' \
        -d '{
          "customer_id": "user_or_org_id_from_auth",
          "plan_id": "pro",
          "redirect_mode": "always"
        }'
        ```
      </CodeGroup>

      <Note>
        Use Stripe's test card `4242 4242 4242 4242` to make a purchase in sandbox.
        You can enter any Expiry and CVV.
      </Note>

      This can be used for any plan changes scenario (upgrades, downgrades, one-time topups, renewals, etc).

      Upgrades will happen immediately, and downgrades will be scheduled for the next billing cycle.

      <Note>
        The **`redirectMode: "always"`** flag will always return a payment URL.

        New purchases redirect to Stripe Checkout to enter payment details, and subsequent charges redirect to an Autumn hosted, one-click confirmation page.

        You can build your own billing confirmation flows by using the [previewAttach](/api-reference/billing/previewAttach) function.
      </Note>
    </Step>
  </Steps>
</View>

**Next: Track and limit usage**

Now that the plan is enabled and you've handled payments, you can now make sure that customers have the access to the right features and limits based on their plan.

<Card title="Track and limit usage" href="/documentation/getting-started/gating">
  Enforce usage limits and feature permissions using Autumn's `check` and
  `track` functions
</Card>