> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/useautumn/autumn/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with Autumn in minutes

## Choose Your Path

You have two options to get started with Autumn:

<CardGroup cols={2}>
  <Card title="Cloud (Recommended)" icon="cloud">
    The fastest way to start - no setup required
  </Card>

  <Card title="Self-Hosted" icon="server">
    Run Autumn on your own infrastructure
  </Card>
</CardGroup>

## Cloud Setup

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

<Steps>
  <Step title="Sign up for Autumn Cloud">
    Visit [app.useautumn.com](https://app.useautumn.com) and create your account.
  </Step>

  <Step title="Get your API keys">
    Navigate to Settings → API Keys in your dashboard and copy your secret key.
  </Step>

  <Step title="Install the SDK">
    Install the Autumn SDK in your project:

    <CodeGroup>
      ```bash npm theme={null}
      npm install @useautumn/sdk
      ```

      ```bash pnpm theme={null}
      pnpm add @useautumn/sdk
      ```

      ```bash bun theme={null}
      bun add @useautumn/sdk
      ```

      ```bash yarn theme={null}
      yarn add @useautumn/sdk
      ```
    </CodeGroup>
  </Step>

  <Step title="Initialize the client">
    Create an Autumn client instance with your API key:

    ```typescript theme={null}
    import { Autumn } from "@useautumn/sdk";

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

    <Warning>
      Never expose your secret key in client-side code. Always use environment variables and server-side API routes.
    </Warning>
  </Step>
</Steps>

## Local Development Setup

To run Autumn locally on your machine:

<Steps>
  <Step title="Install Bun">
    Autumn requires [Bun](https://bun.sh) as its runtime. Install it if you haven't already:

    ```bash theme={null}
    curl -fsSL https://bun.sh/install | bash
    ```
  </Step>

  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/useautumn/autumn.git
    cd autumn
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    bun install
    ```
  </Step>

  <Step title="Run the setup script">
    The setup script will initialize environment variables and optionally create a Supabase instance:

    ```bash theme={null}
    bun setup
    ```

    <Note>
      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`.
    </Note>
  </Step>

  <Step title="Generate database tables">
    ```bash theme={null}
    bun db:generate && bun db:migrate
    ```
  </Step>

  <Step title="Start Autumn with Docker">
    <CodeGroup>
      ```bash Windows theme={null}
      docker compose -f docker-compose.dev.yml up
      ```

      ```bash macOS/Linux theme={null}
      docker compose -f docker-compose.unix.yml up
      ```
    </CodeGroup>

    The Autumn dashboard will be available at `http://localhost:3000`.
  </Step>

  <Step title="Sign in to the dashboard">
    Enter your email at the sign-in page. An OTP will appear in your console/terminal.

    <Note>
      In production, Autumn uses Resend to email OTPs or Google OAuth. Configure these by providing your credentials in `server/.env`.
    </Note>
  </Step>
</Steps>

## Create Your First Product

Once you're logged in to the dashboard:

<Steps>
  <Step title="Create a product">
    Navigate to Products → Create Product and define your first product (e.g., "Pro Plan").
  </Step>

  <Step title="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)
  </Step>

  <Step title="Set pricing">
    Configure your pricing model:

    * Recurring subscription (monthly/yearly)
    * Usage-based with overages
    * One-time purchase
    * Credits and top-ups
  </Step>
</Steps>

## Integrate with Your App

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

### Create or Get a Customer

```typescript theme={null}
const customer = await autumn.customers.getOrCreate({
  id: "user_123",
  name: "John Doe",
  email: "john@example.com"
});
```

### Attach a Plan to a Customer

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
const { data } = await autumn.check({
  customerId: "user_123",
  featureId: "messages",
  requiredBalance: 3,
  sendEvent: true // Atomically consume 3 units if allowed
});
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Self-Hosting Guide" icon="server" href="/self-hosting">
    Learn how to deploy Autumn on your own infrastructure
  </Card>

  <Card title="API Reference" icon="code" href="/api/overview">
    Explore all available endpoints and operations
  </Card>

  <Card title="React Integration" icon="react" href="/sdks/javascript/react-hooks">
    Use Autumn with React hooks and components
  </Card>

  <Card title="Webhooks" icon="webhook" href="/integration/webhooks">
    Set up webhooks to react to billing events
  </Card>
</CardGroup>

## Troubleshooting

<Warning>
  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](https://github.com/drizzle-team/drizzle-orm/issues/4529) 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
</Warning>

<Note>
  Need help? Join our [Discord community](https://discord.gg/53emPtY9tA) or reach out at [hey@useautumn.com](mailto:hey@useautumn.com)
</Note>