autumn-best-practices

name: autumn-best-practices description: Skill for integrating 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 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

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 - Checkout URL is data.url, not data.checkout_url
2. Frontend checks - For UX only. Always enforce on backend
3. Track after success - Only track usage after 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 existing customer if ID exists

Resources

• Docs
• API Reference
• LLMs.txt
• GitHub