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
Resources
-
Docs
-
API Reference
-
LLMs.txt
-
GitHub