- カスタムクレジットエンタイトルメント(トークン)と、そこから自動的に差し引くメーターを作成する
- クレジットをサブスクリプションプラン(超過利用あり/なし)と一回限りの追加購入商品に関連付ける
- 実際のOpenAI completionエンドポイントを接続し、Dodo Paymentsを通じてトークンを請求する
- SDK経由で顧客の現在のクレジット残高を照会する
- webhook署名を検証し、Dodo Paymentsのクレジットイベントを振り分ける
構築するもの
NeuralAPIの料金モデルは次のとおりです。- Dodo Paymentsアカウント(テストモードで可)
- OpenAI APIキー
- Node.js 18以降
- TypeScript/Node.jsの基本的な知識
Step 1:トークンクレジットエンタイトルメントを作成する
まず、両方のサブスクリプションプランと追加購入パックで共有するクレジットエンタイトルメントを作成します。これは、プラットフォームで使用する「トークン」単位を定義するものです。
The Credits tab under Products shows all your credit entitlements.
Navigate to Credits
- Dodo Paymentsダッシュボードにログインします
- 左サイドバーでProductsをクリックします
- Creditsタブを選択します
- Create Creditをクリックします
Configure the credit unit
API TokensCredit Type:Custom Unitを選択しますUnit Name:tokenPrecision:0(トークンは常に整数です)Credit Expiry:30 days(各請求サイクルでクレジットをリセットします)Skip overage at the credit level
Save and copy the credit ID
cent_xxxxxxxxxxxxです。API Tokensクレジットエンタイトルメントの準備ができました。次に、使用量イベントから自動的に差し引けるよう、メーターを作成します。Step 2:トークン使用量のメーターを作成する
メーターは受信した使用量イベントを集計し、クレジットの差し引きに変換します。Step 3で商品作成時に関連付けるため、プラン商品を作成する前に必要です。Open the Meters section
- ダッシュボードのサイドバーでProducts → Metersに移動します
- Create Meterをクリックします
Configure the meter
Token Usage MeterEvent Name:api.tokens_used(アプリが送信する値と完全に一致させる必要があります)Aggregation Type:Sum — 各イベントのトークン数を合計しますOver Property:tokens — 値を合計する各イベントのmetadataキーですMeasurement Unit:tokensメーターを保存し、IDをコピーします。商品に関連付ける際に参照します。Step 3:プラン商品を作成する
両方のプランは通常のSubscriptionsではなく、Usage Based Billing商品にする必要があります。メーターを関連付けられるのはUBB商品だけで、顧客がAPIを呼び出すたびにクレジットを自動で差し引くにはメーターが必要です。UBB商品では定期的な基本料金($29 / $99)も引き続き利用できます。その上の使用量はクレジットで請求されます。

Usage Based Billing pricing type with meter configuration.
Starter Plan($29/月 — 10Mトークン、超過利用なし)
Create the Starter UBB product
- Products → Create Productに移動します
- 料金タイプとしてUsage Based Billingを選択します
- 次を入力します。
NeuralAPI StarterDescription:10 million API tokens per month. Perfect for individual developers and small projects.Fixed Price:29.00(定期的な基本料金。使用量がなくても毎月請求されます)Billing Cycle:MonthlyCurrency:USDAttach the meter
Token Usage Meterを追加します。次にメーターで次を設定します。- Bill usage in Creditsをオンにします
- Credit Entitlement:
API Tokensを選択します - Meter units per credit:
1— イベント内の各トークンが1クレジットの差し引きに対応します - Free Threshold:
0— クレジット割当自体が顧客の「無料枠」なので、追加の無料帯は不要です

Toggle 'Bill usage in Credits' on the meter and pick the credit entitlement.
api.tokens_usedイベントを顧客の残高から実際に差し引くための接続設定です。Configure credit issuance for Starter
10000000Allow Overage:無効 — Starterの顧客はトークンを使い切るとブロックされますImport Default Credit Settings:有効 — クレジットエンタイトルメントの30日間の有効期限を使用します
Configure credit issuance per cycle on the UBB product.
Pro Plan($99/月 — 40Mトークン、超過利用有効)
Create the Pro UBB product
NeuralAPI ProDescription:40 million API tokens per month with overage. Built for production applications.Fixed Price:99.00Billing Cycle:MonthlyCurrency:USDAttach the meter
Token Usage Meterを追加し、Bill usage in Creditsをオンにして、API Tokensを選択します。Meter units per creditは1、Free Thresholdは0です。Configure credit issuance with overage
40000000Import Default Credit Settings:無効 — 商品ごとに超過利用設定をカスタマイズしますAllow Overage:有効Price Per Unit:0.000005 USD/トークン(1Kトークンあたり5。超過利用を抑えるため、プランの実質的なトークン単価より高く設定します)Overage Behavior:Bill overage at billing — 超過利用分は次回請求書に加算され、その後残高がリセットされます商品を保存し、商品IDをコピーします。Step 4:トークン追加購入パックを作成する
追加購入パックは、既存顧客の残高に5,000,000トークンを付与する一回限りの購入です。
Single Payment pricing selected for a one-time credit product.
Create a one-time product
- Products → Create Productに移動します
- 料金タイプとしてSingle Paymentを選択します
- 次を入力します。
Token Top-Up PackDescription:Instantly add 5 million tokens to your NeuralAPI balance.Price:19.00Currency:USDAttach the token credit
- Entitlementsセクションで、Creditsの横にあるAttachをクリックします
API Tokensを選択します- Credits issuedを
5000000に設定します - Import Default Credit Settingsを無効にします — デフォルトの30日間の有効期限を上書きします
- Credit Expiryを
365 daysに設定します - 商品を保存します
Step 5:バックエンドを構築する
次に、サブスクリプションのcheckout、追加購入のcheckout、トークン請求を伴う実際のOpenAI completion、残高照会、クレジットwebhookイベントを処理するExpressサーバーを構築します。Set up your project
tsconfig.jsonを作成します。package.jsonのscriptsを更新します。Set up environment variables
.envを作成します。DODO_PAYMENTS_WEBHOOK_KEYを入力します。Implement the server
src/server.tsを作成します。A note on how deductions actually happen
- ハンドラーがOpenAIを呼び出し、
usage.total_tokens(例:1532)を取得します。 - 1件の使用量イベントを取り込みます:
event_name: api.tokens_used、metadata: { tokens: 1532 }。 Token Usage Meterが顧客ごとにイベントを集計します。- メーターがBill usage in Credits付きで
API Tokensクレジットに接続されているため、Dodo Paymentsは顧客の最も古い有効期限未到来の付与分からFIFOで1,532クレジットを差し引きます。 - 超過利用が有効で顧客が0未満になった場合、不足分が記録され、次回請求書で請求されます。
Step 6:デモフロントエンドを追加する
ブラウザーで全フローをテストするため、public/index.htmlを作成します。顧客IDをlocalStorageに保存することで、subscribe → generate → top-upが同じIDを共有し、ログイン済みアプリを再現します。
Step 7:webhookを接続する
webhookを使うと、サーバーは残高の変化に反応できます。顧客が残高0に達する前に「残りわずか」メールを送信するために使用します。Expose your local server
Register the webhook in Dodo Payments
- ダッシュボードでDevelopers → Webhooks → Add Endpointに移動します
- URL:
https://your-tunnel.ngrok-free.app/webhooks/dodo - 最低限、次のイベントを購読します。
credit.addedcredit.deductedcredit.overage_charged
- 保存してSigning Secretをコピーします
.envにDODO_PAYMENTS_WEBHOOK_KEYとして貼り付け、npm run devを再起動します
Step 8:フロー全体をテストする
Subscribe a test customer
npm run devを実行しますhttp://localhost:3000を開きます- Pro Planを選択し、テスト用メールアドレスと名前を入力してGet Checkout Linkをクリックし、テストカード情報でcheckoutを完了します
- ダッシュボードでCustomers → 最新の顧客に移動し、
cus_...IDをコピーします - デモの「Logged-in customer ID」フィールドに貼り付け、Saveをクリックします
Generate a real AI response
total_tokensを取得し、使用量イベントを取り込んでレスポンスを返します。Test the top-up flow
credit.addedイベントが表示されます。トラブルシューティング
Credits not deducting after usage events
Credits not deducting after usage events
- メーターのイベント名が送信している
event_nameと一致していない(api.tokens_usedは大文字と小文字を区別します) - メーターが商品上の
API Tokensクレジットにリンクされていない — 商品のメーター設定でBill usage in Creditsがオンか確認します metadata.tokensキーがメーターの「Over Property」フィールドと一致していない- 顧客の付与分が期限切れになっている(顧客のクレジット履歴を確認します)
- Products → Meters:メーターを開き、商品への関連付けにリンク済みクレジット名が表示されていることを確認します
- メーターのEventsタブ:差し引き前でも取り込まれたイベントが表示されます
- Customers → [Customer] → Credits:1〜2分以内に台帳エントリが表示されます
Balance always shows 0 or 'customer not found'
Balance always shows 0 or 'customer not found'
- 顧客がまだcheckoutを完了していない — クレジットは支払い成功後にのみ付与されます
- 間違った
customer_idで照会している(自分のDB IDではなく、ダッシュボードのcus_...IDを使用します) .env内のCREDIT_ENTITLEMENT_IDが、商品に関連付けたクレジットと一致していない
Overage not working for Pro plan customers
Overage not working for Pro plan customers
- Pro商品へのクレジット関連付けで超過利用が有効になっていない(クレジットレベルの設定はデフォルトにすぎません)
- 顧客が実際にはProではなくStarterを利用している
- 超過利用の上限が0に設定されている
0.000005(= 100万トークンあたり$5)であることを確認します。先頭のゼロを再確認してください。このフィールドは1Kあたりではなく、トークン単位の価格を受け取ります。`Webhook verification failed` in logs
`Webhook verification failed` in logs
- 本文解析の順序:
express.json()が/webhooks/dodoに対してexpress.raw()より先に適用されている — SDKには解析済みJSONではなくリクエストのraw bytesが必要です DODO_PAYMENTS_WEBHOOK_KEYの署名シークレットが間違っている- リバースプロキシがヘッダーを書き換えている
server.ts内で、app.use('/webhooks/dodo', express.raw(...))の行がapp.use(express.json())より前にあることを確認します。サポートが必要ですか?
おめでとうございます!NeuralAPIにクレジットベースの請求を構築しました
これで、プラットフォームに本番環境対応の完全なクレジット請求システムが備わりました。Token Credit Entitlement
API TokensクレジットTiered Plans, One Credit
One-Time Top-Up Pack
Auto-Deduction via Meter
Live Balance API
Verified Webhook Pipeline
credit.added、credit.deducted、credit.overage_charged)を、SDKのStandard Webhooksヘルパーを使う署名検証済みハンドラーで処理/credits/:customerIdと/api/generateの認証 — 現在は誰でも任意の顧客IDで呼び出せます。ユーザーを認証し、サーバー側でそのユーザー自身の顧客IDを検索してください。- 安定した
event_ids — 例ではDate.now() + randomを使用しています。本番環境ではリクエストIDを使用して再試行を冪等にしてください(Dodo Paymentsはevent_idで重複排除します)。 - 顧客とユーザーの対応関係を永続化 — 初回checkout後に
customer_idをDBに保存し、手動貼り付けの手順を不要にします。 - サブスクリプション終了時の動作を決める。プランのクレジットは自然に期限切れになるまで顧客の台帳に残り(付与から30日)、追加購入クレジットは365日間有効です。ただし、このcookbookの
/api/generateは残高だけを確認し、サブスクリプションの状態は確認しません。そのため、解約した顧客も残りのトークンを使えます。これは消費者に優しいデフォルトです。より厳格なアクセス制御が必要な場合は、(a)subscription.cancelledwebhookを監視してサブスクリプション状態に基づき/api/generateを制御するか、(b) Dodoの台帳APIを呼び出し、解約時に未使用のプランクレジットを差し引き、追加購入クレジットは維持します。 - Usage Billingダッシュボードを監視して、メーターの異常を早期に検出します。