autumn-best-practices

Original：🇺🇸 English

Translated

Skill for integrating Autumn - the billing and entitlements layer over Stripe.

2installs

Sourceuseautumn/skills

Added on2026-03-08

NPX Install

npx skill4agent add useautumn/skills autumn-best-practices

SKILL.md Content

View Translation Comparison →

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

bash

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:

typescript

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

typescript

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

tsx

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