Autumn Setup

Set up Autumn Billing

Autumn is a billing and entitlements layer over Stripe. This skill walks through installing the SDK, creating an Autumn customer, and wiring up the payment flow.

Before starting: Check for an autumn.config.ts in the project root. If it doesn't exist, run npx atmn init to log in and generate the file (this saves your API key and syncs your config). Then refer to autumn.config.ts for your product and feature IDs.

Step 1: Analyze the Codebase

Before making changes, detect:

• Language: TypeScript/JavaScript, Python, or other
• If TS/JS - Framework: Next.js, Hono, or other
• If TS/JS - React frontend?: Check for React in package.json
• Customer model: Look at the auth setup to determine whether customers map to individual users or organizations. Check for org/team/workspace models in the codebase.

If it's clear from the codebase (e.g., there's an org model and team-based auth), state your assumption. If it's ambiguous, ask the user:

Should Autumn customers be individual users, or organizations?

• Users (B2C): Each user has their own plan and limits
• Organizations (B2B): Plans and limits are shared across an org

Step 2: Create a Plan and Confirm

Before writing any integration code, present a short plan to the user covering:

• What stack/framework you detected
• Whether customers are users or orgs (and why you think so)
• Which path you're following (React fullstack vs backend-only)
• Which files you'll create or modify
• Where the handler / provider / customer creation will go
• Where the payment flow will be wired up

Ask the user to read, edit, and confirm the plan before proceeding. Do NOT start coding until the user approves.

Path A: React + Node.js (Fullstack TypeScript)

Use this path if there's a React frontend with a Node.js backend.

A1. Install the SDK

Use the package manager already installed (npm, yarn, pnpm, bun):

npm install autumn-js

A2. Mount the Handler (Server-Side)

This creates endpoints at /api/autumn/* that the React hooks will call. The identify function should return either the user ID or org ID from your auth provider, depending on how you're using Autumn.

Next.js (App Router)

// app/api/autumn/[...all]/route.ts
import { autumnHandler } from "autumn-js/next";

export const { GET, POST } = autumnHandler({
  identify: async (request) => {
    // Get user/org from your auth provider
    const session = await auth.api.getSession({ headers: request.headers });
    return {
      customerId: session?.user.id, // or session?.org.id for B2B
      customerData: {
        name: session?.user.name,
        email: session?.user.email,
      },
    };
  },
});

Hono

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

app.use("/api/autumn/*", autumnHandler({
  identify: async (c) => {
    const session = await auth.api.getSession({ headers: c.req.raw.headers });
    return {
      customerId: session?.user.id, // or session?.org.id for B2B
      customerData: { name: session?.user.name, email: session?.user.email },
    };
  },
}));

Other Frameworks (Generic Handler)

For any framework not listed above, use the generic handler:

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

// Mount this handler onto the /api/autumn/* path in your backend
const handleRequest = async (request) => {
  const session = await auth.api.getSession({ headers: request.headers });

  let body = null;
  if (request.method !== "GET") {
    body = await request.json();
  }

  const { statusCode, response } = await autumnHandler({
    customerId: session?.user.id,
    customerData: {
      name: session?.user.name,
      email: session?.user.email,
    },
    request: {
      url: request.url,
      method: request.method,
      body: body,
    },
  });

  return new Response(JSON.stringify(response), {
    status: statusCode,
    headers: { "Content-Type": "application/json" },
  });
};

A3. Add the Provider (Client-Side)

Wrap your app with AutumnProvider:

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

export default function RootLayout({ children }) {
  return (
    <AutumnProvider>
      {children}
    </AutumnProvider>
  );
}

If your backend is on a different URL (e.g., Vite + separate server), pass backendUrl:

<AutumnProvider backendUrl={import.meta.env.VITE_BACKEND_URL}>

A4. Create a Customer

Add this hook to any component. It automatically creates an Autumn customer for new users and fetches existing customer state:

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

const { data } = useCustomer();
console.log("Autumn customer:", data);

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

A5. Stripe Payment Flow

Call attach when the customer wants to purchase a plan. This returns a Stripe payment URL. Once they pay, Autumn grants access to the features defined in the plan.

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

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

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

This handles all plan change scenarios (upgrades, downgrades, one-time topups, renewals, etc).

The redirectMode: "always" flag always returns a payment URL:

• New purchases redirect to Stripe Checkout to enter payment details
• Subsequent charges redirect to an Autumn hosted, one-click confirmation page

Path B: Backend Only (Node.js, Python, or Other)

Use this path if there's no React frontend, or you prefer server-side only.

B1. Install the SDK

Node.js:

npm install autumn-js

Python:

pip install autumn-sdk

B2. Initialize the Client

TypeScript/JavaScript:

import { Autumn } from "autumn-js";

const autumn = new Autumn({
  secretKey: process.env.AUTUMN_SECRET_KEY,
});

Python:

from autumn_sdk import Autumn

autumn = Autumn('am_sk_test_xxx')

B3. Create a Customer

When the customer signs up, create an Autumn customer. Autumn will automatically enable any autoEnable plan (typically Free).

TypeScript:

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

Python:

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

cURL:

curl -X POST https://api.useautumn.com/v1/customers \
  -H "Authorization: Bearer am_sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "user_or_org_id_from_auth", "name": "John Doe", "email": "john@example.com"}'

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

B4. Stripe Payment Flow

Call attach when the customer wants to purchase a plan. This returns a Stripe payment URL. Redirect the customer to complete payment.

TypeScript:

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

redirect(response.paymentUrl);

Python:

response = await autumn.billing.attach(
    customer_id="user_or_org_id_from_auth",
    plan_id="pro",
    redirect_mode="always",
)
# Redirect to response.payment_url

cURL:

curl -X POST 'https://api.useautumn.com/v1/attach' \
  -H 'Authorization: Bearer am_sk_test_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "user_or_org_id_from_auth",
    "plan_id": "pro",
    "redirect_mode": "always"
  }'

This handles all plan change scenarios (upgrades, downgrades, one-time topups, renewals, etc).

The redirectMode: "always" flag always returns a payment URL:

• New purchases redirect to Stripe Checkout to enter payment details
• Subsequent charges redirect to an Autumn hosted, one-click confirmation page

Verification

After setup, report to the user:

1. What stack you detected
2. Which path you followed
3. What files you created/modified
4. That the Autumn customer is logged in browser, and to check in the Autumn dashboard

Note: Your Autumn configuration is in autumn.config.ts in your project root.

Documentation: https://docs.useautumn.com/llms.txt