Quickstart

Get started with Autumn in minutes

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

   npm install @useautumn/sdk
   

   pnpm add @useautumn/sdk
   

   bun add @useautumn/sdk
   

   yarn add @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

   Windows

   docker compose -f docker-compose.dev.yml up
   

   docker compose -f docker-compose.unix.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: "[e-mail]"
});

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 [e-mail]