Autumn Integration Guide

Always consult docs.useautumn.com for code examples and latest API.

Autumn is a TypeScript-first billing SDK supporting subscriptions, usage-based pricing, credits, trials, and more via Stripe.

Quick Reference

Environment Variables

AUTUMN_SECRET_KEY - API key (required). Get one at app.useautumn.com

Installation

npm install autumn-js    # Node.js
pip install autumn-py    # Python

Core Methods

| Method | Purpose | |--------|---------| | customers.create | Create or get customer (idempotent) | | checkout | Get Stripe URL or payment preview | | attach | Confirm purchase (card on file) | | cancel | Cancel subscription | | check | Verify feature access | | track | Record usage | | products.list | Get products with billing scenarios |

Core Config Options

| Option | Notes | |--------|-------| | secretKey | Required. From env AUTUMN_SECRET_KEY | | baseURL | Optional. Defaults to https://api.useautumn.com |

Billing Patterns

Check → Work → Track

Always follow this order for protected actions:

const { data } = await autumn.check({ customer_id, feature_id: "api_calls" });
if (!data.allowed) return { error: "Limit reached" };

const result = await doWork();

await autumn.track({ customer_id, feature_id: "api_calls", value: 1 });
return result;

Two-Step Checkout

const { data } = await autumn.checkout({ customer_id, product_id: "pro" });

if (data.url) return redirect(data.url);  // New customer → Stripe

// Returning customer → show confirmation, then:
await autumn.attach({ customer_id, product_id: "pro" });

Product Scenarios

Use products.list to get scenarios. Don't build custom logic.

| Scenario | Meaning | |----------|---------| | new | Not subscribed | | active | Currently on plan | | scheduled | Scheduled for future | | upgrade | Higher tier available | | downgrade | Lower tier available | | renew | Cancelled, can reactivate |

Feature Types

| Type | Behavior | |------|----------| | boolean | Access granted or denied | | metered | Usage tracked against limit | | credit_system | Pool for multiple features |

React Hooks

| Hook | Purpose | |------|---------| | useCustomer | Get customer, checkout, attach, check | | usePricingTable | Get products with scenarios |

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

<AutumnProvider>{children}</AutumnProvider>

Handler Imports

| Framework | Import | |-----------|--------| | Next.js | autumn-js/next | | React Router | autumn-js/react-router | | Hono | autumn-js/hono | | Express | autumn-js/express | | Fastify | autumn-js/fastify | | Generic | autumn-js/backend |

Common Gotchas

URL field - Checkout URL is data.url, not data.checkout_url
Frontend checks - For UX only. Always enforce on backend
Track after success - Only track usage after work completes
Credit systems - Track metered features, not the credit system itself
Cancel via free plan - Prefer attach({ product_id: "free" }) over cancel()
Idempotent creation - customers.create returns existing customer if ID exists

autumn-best-practices