Installation & Setup

Install and configure the Autumn JavaScript/TypeScript SDK

Installation

Install the autumn-js package using your preferred package manager:

npm

npm install autumn-js

yarn add autumn-js

pnpm add autumn-js

bun add autumn-js

Package Exports

The SDK provides multiple entry points for different use cases:

• autumn-js - Core SDK (re-exports from @useautumn/sdk)
• autumn-js/react - React hooks and provider
• autumn-js/backend - Backend integration utilities
• autumn-js/hono - Hono framework adapter
• autumn-js/next - Next.js framework adapter
• autumn-js/better-auth - Better Auth plugin

Quick Start

Frontend (React)

Wrap your app with the AutumnProvider to enable React hooks:

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

function App() {
  return (
    <AutumnProvider
      backendUrl="https://api.example.com"
      pathPrefix="/api/autumn"
    >
      <YourApp />
    </AutumnProvider>
  );
}

Provider Props

backendUrl · string

Base URL for your backend server (e.g., "https://api.example.com"). Defaults to the current origin.

pathPrefix · string

Path prefix for Autumn routes. Defaults to "/api/autumn", or "/api/auth/autumn" if useBetterAuth is enabled.

useBetterAuth · boolean

Enable Better Auth integration. Sets pathPrefix to "/api/auth/autumn" and includeCredentials to true.

includeCredentials · boolean

Include credentials (cookies) in cross-origin requests. Defaults to true if useBetterAuth is enabled.

Backend (Next.js)

Create an API route to handle Autumn requests:

// app/api/autumn/[...autumn]/route.ts
import { autumnHandler } from 'autumn-js/next';
import { cookies } from 'next/headers';

const handler = autumnHandler({
  secretKey: process.env.AUTUMN_SECRET_KEY,
  identify: async (request) => {
    // Extract user ID from your auth system
    const sessionCookie = cookies().get('session');
    if (!sessionCookie) return null;
    
    const userId = await validateSession(sessionCookie.value);
    return { customerId: userId };
  },
});

export { handler as GET, handler as POST, handler as DELETE };

Backend (Hono)

Add the Autumn middleware to your Hono app:

import { Hono } from 'hono';
import { autumnHandler } from 'autumn-js/hono';

const app = new Hono();

app.use('/api/autumn/*', autumnHandler({
  secretKey: process.env.AUTUMN_SECRET_KEY,
  identify: async (c) => {
    // Extract user ID from context
    const user = c.get('user');
    if (!user) return null;
    
    return { customerId: user.id };
  },
}));

Better Auth Integration

If you’re using Better Auth, install the Autumn plugin:

Backend Setup

import { betterAuth } from 'better-auth';
import { autumn } from 'autumn-js/better-auth';

export const auth = betterAuth({
  // ... your auth config
  plugins: [
    autumn({
      secretKey: process.env.AUTUMN_SECRET_KEY,
      customerScope: 'user', // 'user' | 'organization' | 'user_and_organization'
    }),
  ],
});

Frontend Setup

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

function App() {
  return (
    <AutumnProvider useBetterAuth>
      <YourApp />
    </AutumnProvider>
  );
}

Customer Scope Options

customerScope · 'user' | 'organization' | 'user_and_organization' · default: "user"

Determines how customer identity is resolved:

• user - Customer ID is the user’s ID
• organization - Customer ID is the active organization’s ID
• user_and_organization - Customer ID combines user and organization IDs

Custom Identity Resolution

For advanced use cases, provide a custom identify function:

autumn({
  secretKey: process.env.AUTUMN_SECRET_KEY,
  identify: ({ session, organization }) => {
    if (!session) return null;
    
    // Custom logic to determine customer ID
    const customerId = organization?.id ?? session.user.id;
    
    return {
      customerId,
      customerData: {
        email: session.user.email,
        name: organization?.name ?? session.user.name,
      },
    };
  },
})

Environment Variables

AUTUMN_SECRET_KEY · string · required

Your Autumn API secret key. Get this from your Autumn dashboard.

TypeScript Support

The SDK is written in TypeScript and provides full type definitions. All hooks, methods, and responses are fully typed:

import { useCustomer } from 'autumn-js/react';
import type { Customer, AttachResponse } from 'autumn-js';

function MyComponent() {
  const { data, attach } = useCustomer();
  
  // `data` is typed as Customer | null | undefined
  // `attach` returns Promise<AttachResponse>
}

Error Handling

All client methods throw AutumnClientError on failure:

import { AutumnClientError } from 'autumn-js/react';

try {
  await attach({ planId: 'plan_123' });
} catch (error) {
  if (error instanceof AutumnClientError) {
    console.error('Error:', error.message);
    console.error('Code:', error.code);
    console.error('Status:', error.statusCode);
    console.error('Details:', error.details);
  }
}

AutumnClientError Properties

message · string

Human-readable error message

code · string

Machine-readable error code

statusCode · number

HTTP status code

details · unknown

Additional error details if available

Next Steps

React Hooks

Learn about all available React hooks

Backend Integration

Set up backend handlers and custom routes