Setup and payments

Autumn’s client-side hooks are supported for fullstack TypeScript apps. Please use the Server SDK for other frameworks.

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.

Browse our Examples for guides on setting up credit systems, top ups and other common pricing models.

CLI
Dashboard

Run the following command in your root directory:

bunx atmn init

npx atmn init

pnpm dlx atmn init

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 to build your own.

autumn.config.ts

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.

bunx atmn push

npx atmn push

pnpm dlx atmn push

If you already have products created in the dashboard, run atmn pull to pull them into your local config.

Create your Autumn account, and the Free and Pro plans in the Plans tab.

Free Plan

On the Plans 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

Your Free plan should look like this

Pro Plan

On the Plans 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

Your Pro plan should look like this

Installation

Create an Autumn Secret key, and paste it in your .env variables. Then, install the Autumn SDK. If you’re using the CLI, this will be done for you.

.env

AUTUMN_SECRET_KEY=am_sk_test_42424242...

bun add autumn-js

npm install autumn-js

pnpm add autumn-js

yarn add autumn-js

If you’re using a separate backend and frontend, make sure to install the library in both.

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.

// 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,
            },
        };
    },
});

// 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,
                },
            };
        },
    }),
);

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

// 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);

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

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.

Add Provider Client-side

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

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

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

Create an Autumn customer

From a frontend component, use the useCustomer() hook. This will automatically create an Autumn customer if they’re a new user and enable the Free plan for them, or get the customer’s state for existing users.

React

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

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

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

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

Show data object

{
    "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
        }
    }
}

You will see your user under the customers page in the Autumn dashboard.

Stripe Payment Flow

Call attach when the customer wants to purchase the Pro 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.

Use Stripe’s test card 4242 4242 4242 4242 to make a purchase in sandbox. You can enter any Expiry and CVV.

React

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.

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 function.

Getting Started

Configure Pricing

Billing & Subscriptions

Customers

Additional Resources

Lakehouse

Setup and payments

Create your pricing plans

Installation

Add Endpoints Server-side

Add Provider Client-side

Create an Autumn customer

Stripe Payment Flow

Track and limit usage

​Create your pricing plans

​Installation

​Add Endpoints Server-side

​Add Provider Client-side

​Create an Autumn customer

​Stripe Payment Flow

Track and limit usage

Create your pricing plans

Installation

Add Endpoints Server-side

Add Provider Client-side

Create an Autumn customer

Stripe Payment Flow