autumn-best-practices

Autumn 統合ガイド

コード例と最新の API については、必ず docs.useautumn.com を参照してください。

Autumn は、Stripe を介してサブスクリプション、従量課金、クレジット、トライアルなどに対応する、TypeScript ファーストの課金 SDK です。

---

クイックリファレンス

環境変数

• AUTUMN_SECRET_KEY - API キー（必須）。app.useautumn.com で取得できます

インストール

npm install autumn-js    # Node.js
pip install autumn-py    # Python

コアメソッド

メソッド	用途
customers.create	顧客を作成または取得します（冪等）
checkout	Stripe の URL または支払いプレビューを取得します
attach	購入を確定します（登録済みカードを使用）
cancel	サブスクリプションをキャンセルします
check	機能へのアクセスを確認します
track	使用量を記録します
products.list	課金シナリオ付きの商品を取得します

---

コア設定オプション

オプション	備考
secretKey	必須。環境変数 AUTUMN_SECRET_KEY から取得します
baseURL	任意。デフォルトは https://api.useautumn.com です

---

課金パターン

確認 → 実行 → 記録

アクセス制限のある操作では、必ず次の順序に従ってください。

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;

2 段階チェックアウト

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" });

---

商品シナリオ

シナリオを取得するには、products.list を使用します。独自のロジックは作成しないでください。

シナリオ	意味
new	未登録
active	現在プランを利用中
scheduled	将来の開始が予定されています
upgrade	上位ティアを利用できます
downgrade	下位ティアを利用できます
renew	キャンセル済みですが、再開できます

---

機能タイプ

タイプ	動作
boolean	アクセスを許可または拒否します
metered	使用量を上限に対して追跡します
credit_system	複数の機能で使えるプールです

---

React フック

フック	用途
useCustomer	顧客の取得、チェックアウト、購入確定、確認
usePricingTable	シナリオ付きの商品を取得します

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

<AutumnProvider>{children}</AutumnProvider>

---

ハンドラーのインポート

フレームワーク	インポート
Next.js	autumn-js/next
React Router	autumn-js/react-router
Hono	autumn-js/hono
Express	autumn-js/express
Fastify	autumn-js/fastify
汎用	autumn-js/backend

---

よくある注意点

1. URL フィールド - チェックアウト URL は data.checkout_url ではなく data.url です
2. フロントエンドでの確認 - UX のためだけに使用します。必ずバックエンドで適用してください
3. 成功後に記録 - 処理が完了してから使用量を記録してください
4. クレジットシステム - クレジットシステム自体ではなく、従量制の機能を記録してください
5. 無料プラン経由でのキャンセル - cancel() よりも attach({ product_id: "free" }) を推奨します
6. 冪等な作成 - customers.create は ID が存在する場合、既存の顧客を返します

---

リソース

• ドキュメント
• API リファレンス
• LLMs.txt
• GitHub