# Autumn Best Practices

> Integrate Autumn, the billing and entitlements layer over Stripe.

- Skill: `stickerdaniel/autumn-best-practices-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add stickerdaniel/autumn-best-practices-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/stickerdaniel/autumn-best-practices-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: stickerdaniel (https://skillmd.com/u/stickerdaniel)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/stickerdaniel/autumn-best-practices-2

---


# Autumn Integration Guide

**Always consult [docs.useautumn.com](https://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](https://app.useautumn.com/dev?tab=api_keys)

### 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

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](https://docs.useautumn.com)
- [API Reference](https://docs.useautumn.com/api-reference)
- [LLMs.txt](https://docs.useautumn.com/llms.txt)
- [GitHub](https://github.com/useautumn/autumn)