Skip to main content
Autumn’s client-side hooks allow you to handle billing directly from your frontend.
Client libraries are supported for React and Node.js apps. Please use our Server-side SDK for other frameworks and languages.
In this example we’ll create the pricing for a premium AI chatbot. We’re going to have:
  • A Free plan that gives users 5 chat messages per month for free
  • A Pro plan that gives users 100 chat messages per month for $20 per month.
1

​
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.
Create your Autumn account, and the Free and Pro plans in the Plans tab.
  • 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

  • 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

2

​
Installation

Create an Autumn Secret key, and paste it in your .env variables. Then, install the Autumn SDK.
.env
AUTUMN_SECRET_KEY=am_sk_test_42424242...

bun add autumn-js
If you’re using a separate backend and frontend, make sure to install the library in both.
3

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

​
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>
  );
}
The provider accepts the following props:
PropDescription
backendUrlBase URL for the backend server (e.g., https://api.example.com). Defaults to current origin.
pathPrefixPath prefix for the Autumn routes. Defaults to /api/autumn, or /api/auth/autumn if useBetterAuth is true.
useBetterAuthUse better-auth integration. Sets pathPrefix to /api/auth/autumn and includeCredentials to true by default.
includeCredentialsInclude credentials (cookies) in cross-origin requests. Defaults to true if useBetterAuth is true.
5

​
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>
}
You will see your user under the customers page in the Autumn dashboard.
6

​
Stripe Payment Flow

Call attach to attach the Pro plan to the customer. The customer is redirected to an Autumn checkout page where they can review prorations and plan changes before confirming. 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",
        });
        // Hook automatically redirects to Autumn checkout
      }}
    >
      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.
Default behavior: For new subscriptions, the hook redirects to Stripe Checkout. For plan changes (upgrades/downgrades), it redirects to Autumn Checkout where customers can review prorations before confirming.Build your own UI: If you want to handle the checkout for plan changes yourself:
  1. Call previewAttach to get line items and pricing details
  2. Call attach with redirectMode: "if_required" — this charges the customer automatically if they have a payment method on file
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.

Track and limit usage

Enforce usage limits and feature permissions using Autumn’s check and track functions