Autumn Best Practices

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

• 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

Core Config Options

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.

Feature Types

React Hooks

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

<AutumnProvider>{children}</AutumnProvider>;

Handler Imports

Common Gotchas

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

Resources

• Docs
• API Reference
• LLMs.txt
• GitHub