Skip to main content

​
Choose Your Path

You have two options to get started with Autumn:

Cloud (Recommended)

The fastest way to start - no setup required

Self-Hosted

Run Autumn on your own infrastructure

​
Cloud Setup

The quickest way to start using Autumn is through our cloud service.
1

Sign up for Autumn Cloud

Visit app.useautumn.com and create your account.
2

Get your API keys

Navigate to Settings → API Keys in your dashboard and copy your secret key.
3

Install the SDK

Install the Autumn SDK in your project:
npm install @useautumn/sdk
4

Initialize the client

Create an Autumn client instance with your API key:
import { Autumn } from "@useautumn/sdk";

const autumn = new Autumn({
  xApiVersion: "2.1",
  secretKey: process.env.AUTUMN_SECRET_KEY,
});
Never expose your secret key in client-side code. Always use environment variables and server-side API routes.

​
Local Development Setup

To run Autumn locally on your machine:
1

Install Bun

Autumn requires Bun as its runtime. Install it if you haven’t already:
curl -fsSL https://bun.sh/install | bash
2

Clone the repository

git clone https://github.com/useautumn/autumn.git
cd autumn
3

Install dependencies

bun install
4

Run the setup script

The setup script will initialize environment variables and optionally create a Supabase instance:
bun setup
The setup script initializes required env vars and (optionally) a Supabase instance. If you’d like to use your own Postgres instance, paste the connection string in the DATABASE_URL env variable at server/.env.
5

Generate database tables

bun db:generate && bun db:migrate
6

Start Autumn with Docker

docker compose -f docker-compose.dev.yml up
The Autumn dashboard will be available at http://localhost:3000.
7

Sign in to the dashboard

Enter your email at the sign-in page. An OTP will appear in your console/terminal.
In production, Autumn uses Resend to email OTPs or Google OAuth. Configure these by providing your credentials in server/.env.

​
Create Your First Product

Once you’re logged in to the dashboard:
1

Create a product

Navigate to Products → Create Product and define your first product (e.g., “Pro Plan”).
2

Add features

Define the features included in your product:
  • Metered features: API calls, tokens, messages (consumed over time)
  • Boolean features: Access flags for premium features
  • Entity features: Seats, workspaces, projects (allocated resources)
3

Set pricing

Configure your pricing model:
  • Recurring subscription (monthly/yearly)
  • Usage-based with overages
  • One-time purchase
  • Credits and top-ups

​
Integrate with Your App

Now that you have a product set up, integrate Autumn into your application:

​
Create or Get a Customer

const customer = await autumn.customers.getOrCreate({
  id: "user_123",
  name: "John Doe",
  email: "[email protected]"
});

​
Attach a Plan to a Customer

const result = await autumn.billing.attach({
  customerId: "user_123",
  planId: "pro_plan"
});

// If payment is required, redirect to checkout
if (result.paymentUrl) {
  window.location.href = result.paymentUrl;
}

​
Check Access to a Feature

const { data } = await autumn.check({
  customerId: "user_123",
  featureId: "ai_tokens"
});

if (!data.allowed) {
  console.log("Feature access denied");
  console.log("Current balance:", data.balance);
}

​
Track Usage

await autumn.track({
  customerId: "user_123",
  featureId: "ai_tokens",
  value: 100 // Track 100 tokens used
});

​
Check and Track Atomically

You can check access and record usage in a single request: 
const { data } = await autumn.check({
  customerId: "user_123",
  featureId: "messages",
  requiredBalance: 3,
  sendEvent: true // Atomically consume 3 units if allowed
});

​
Next Steps

Self-Hosting Guide

Learn how to deploy Autumn on your own infrastructure

API Reference

Explore all available endpoints and operations

React Integration

Use Autumn with React hooks and components

Webhooks

Set up webhooks to react to billing events

​
Troubleshooting

If you encounter a SyntaxError: Unexpected end of JSON input error when running bun setup again after previously running it, you may need to clear your database tables first. This is a known issue that can occur when running database migrations multiple times.To resolve:
  1. Connect to your database
  2. Drop all existing tables
  3. Run bun setup again
Need help? Join our Discord community or reach out at [email protected]

Build docs developers (and LLMs) love

Get started for freeTalk to us