| name | autumn-best-practices |
| description | Integrate Autumn, the billing and entitlements layer over Stripe. |
Autumn Integration Guide
Always consult docs.useautumn.com for code examples and latest API.
Autumn is a TypeScript-first billing SDK for subscriptions, usage-based pricing, credits, and trials on top of Stripe.
Quick Reference
Environment Variables
Installation
npm install autumn-js
pip install autumn-py
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);
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. The checkout URL is
data.url, not data.checkout_url
- Frontend checks. For UX only. Always enforce on the backend
- Track after success. Only track usage after the 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 the existing customer if the ID exists
Resources
