Skip to main content
Sentraに統合コードの作成を任せましょう。
VS Code、Cursor、またはWindsurfでAIアシスタントを使い、希望する内容を説明するだけでSDK/APIコード、webhookハンドラー、クレジット付与などを生成できます。
Sentraを試す:AI搭載の統合 →
このチュートリアルでは、NeuralAPIを構築します。各サブスクリプションプランに月間トークンクレジット枠が設定され、残量が少なくなった顧客は追加購入パックを購入でき、OpenAIがリクエストを処理するとバックエンドがクレジットを自動的に差し引く階層型AIプラットフォームです。
このチュートリアルではNode.js/Express + OpenAI SDKを使用します。Dodo Paymentsの概念(クレジット、メーター、webhook)は、どのフレームワークやAIプロバイダーにも適用できます。自由に応用してください。
このチュートリアルを終えると、次の方法がわかります。
  • カスタムクレジットエンタイトルメント(トークン)と、そこから自動的に差し引くメーターを作成する
  • クレジットをサブスクリプションプラン(超過利用あり/なし)と一回限りの追加購入商品に関連付ける
  • 実際のOpenAI completionエンドポイントを接続し、Dodo Paymentsを通じてトークンを請求する
  • SDK経由で顧客の現在のクレジット残高を照会する
  • webhook署名を検証し、Dodo Paymentsのクレジットイベントを振り分ける

構築するもの

NeuralAPIの料金モデルは次のとおりです。
開始する前に、次を用意してください。
  • Dodo Paymentsアカウント(テストモードで可)
  • OpenAI APIキー
  • Node.js 18以降
  • TypeScript/Node.jsの基本的な知識

Step 1:トークンクレジットエンタイトルメントを作成する

まず、両方のサブスクリプションプランと追加購入パックで共有するクレジットエンタイトルメントを作成します。これは、プラットフォームで使用する「トークン」単位を定義するものです。
Credits listing page showing created credit entitlements

The Credits tab under Products shows all your credit entitlements.

1

Navigate to Credits

  1. Dodo Paymentsダッシュボードにログインします
  2. 左サイドバーでProductsをクリックします
  3. Creditsタブを選択します
  4. Create Creditをクリックします
2

Configure the credit unit

トークンクレジットの基本情報を入力します。Credit NameAPI TokensCredit TypeCustom Unitを選択しますUnit NametokenPrecision0(トークンは常に整数です)Credit Expiry30 days(各請求サイクルでクレジットをリセットします)
クレジット作成後にPrecisionは変更できません。トークン数には、0(整数)がほぼ常に適切です。
3

Skip overage at the credit level

ここでは超過利用を無効のままにします。クレジットを商品に関連付ける際、プランごとに設定します。これにより、Starterプランでは残高0で利用をブロックし、Proプランでは超過利用を許可できます。
ここで設定する超過利用の設定はデフォルトです。各商品への関連付けで上書きできます。Step 3でまさにその設定を行います。
4

Save and copy the credit ID

Create Creditをクリックします。保存後、クレジットを開いてIDをコピーします。形式はcent_xxxxxxxxxxxxです。
API Tokensクレジットエンタイトルメントの準備ができました。次に、使用量イベントから自動的に差し引けるよう、メーターを作成します。

Step 2:トークン使用量のメーターを作成する

メーターは受信した使用量イベントを集計し、クレジットの差し引きに変換します。Step 3で商品作成時に関連付けるため、プラン商品を作成する前に必要です。
1

Open the Meters section

  1. ダッシュボードのサイドバーでProductsMetersに移動します
  2. Create Meterをクリックします
2

Configure the meter

次を入力します。Meter NameToken Usage MeterEvent Nameapi.tokens_usedアプリが送信する値と完全に一致させる必要がありますAggregation TypeSum — 各イベントのトークン数を合計しますOver Propertytokens — 値を合計する各イベントのmetadataキーですMeasurement Unittokens
イベント名は大文字と小文字を区別します。api.tokens_usedApi.Tokens.Usedです。どちらか一方を選び、統一してください。
メーターを保存し、IDをコピーします。商品に関連付ける際に参照します。
メーターが作成されました。これで商品設定時にクレジットへ接続できます。

Step 3:プラン商品を作成する

両方のプランは通常のSubscriptionsではなく、Usage Based Billing商品にする必要があります。メーターを関連付けられるのはUBB商品だけで、顧客がAPIを呼び出すたびにクレジットを自動で差し引くにはメーターが必要です。UBB商品では定期的な基本料金($29 / $99)も引き続き利用できます。その上の使用量はクレジットで請求されます。
Usage Based Billing pricing configuration

Usage Based Billing pricing type with meter configuration.

Starter Plan($29/月 — 10Mトークン、超過利用なし)

1

Create the Starter UBB product

  1. Products → Create Productに移動します
  2. 料金タイプとしてUsage Based Billingを選択します
  3. 次を入力します。
Product NameNeuralAPI StarterDescription10 million API tokens per month. Perfect for individual developers and small projects.Fixed Price29.00(定期的な基本料金。使用量がなくても毎月請求されます)Billing CycleMonthlyCurrencyUSD
2

Attach the meter

Select meterセクションで**+**をクリックし、Token Usage Meterを追加します。次にメーターで次を設定します。
  1. Bill usage in Creditsをオンにします
  2. Credit EntitlementAPI Tokensを選択します
  3. Meter units per credit1 — イベント内の各トークンが1クレジットの差し引きに対応します
  4. Free Threshold0 — クレジット割当自体が顧客の「無料枠」なので、追加の無料帯は不要です
Meter with Bill usage in Credits enabled and API Tokens selected

Toggle 'Bill usage in Credits' on the meter and pick the credit entitlement.

これが、受信したapi.tokens_usedイベントを顧客の残高から実際に差し引くための接続設定です。
3

Configure credit issuance for Starter

商品画面で、クレジット請求メーターを関連付けると表示されるクレジット設定セクションまでスクロールします。Credits issued per billing cycle10000000Allow Overage無効 — Starterの顧客はトークンを使い切るとブロックされますImport Default Credit Settings:有効 — クレジットエンタイトルメントの30日間の有効期限を使用します
Credit configuration form with per-cycle amount and overage settings

Configure credit issuance per cycle on the UBB product.

Saveをクリックし、商品IDをコピーします。
Starter Plan:$29/月の基本料金、10Mトークン/サイクル、0でブロック、メーター経由で自動差し引き。

Pro Plan($99/月 — 40Mトークン、超過利用有効)

1

Create the Pro UBB product

Starterと同じ流れですが、数値が大きくなります。Product NameNeuralAPI ProDescription40 million API tokens per month with overage. Built for production applications.Fixed Price99.00Billing CycleMonthlyCurrencyUSD
2

Attach the meter

Starterと同じです。Token Usage Meterを追加し、Bill usage in Creditsをオンにして、API Tokensを選択します。Meter units per credit1Free Threshold0です。
3

Configure credit issuance with overage

今回は超過利用を有効にして、クレジット付与を設定します。Credits issued per billing cycle40000000Import Default Credit Settings無効 — 商品ごとに超過利用設定をカスタマイズしますAllow Overage有効Price Per Unit0.000005 USD/トークン(1Kトークンあたり0.005、つまり1Mトークンあたり0.005、つまり1Mトークンあたり5。超過利用を抑えるため、プランの実質的なトークン単価より高く設定します)Overage BehaviorBill overage at billing — 超過利用分は次回請求書に加算され、その後残高がリセットされます商品を保存し、商品IDをコピーします。
Pro Plan:99/月の基本料金、40Mトークン/サイクル、1Kトークンあたり99/月の基本料金、40Mトークン/サイクル、1Kトークンあたり0.005の超過利用、メーター経由で自動差し引き。

Step 4:トークン追加購入パックを作成する

追加購入パックは、既存顧客の残高に5,000,000トークンを付与する一回限りの購入です。
Product pricing section with Single Payment selected

Single Payment pricing selected for a one-time credit product.

1

Create a one-time product

  1. Products → Create Productに移動します
  2. 料金タイプとしてSingle Paymentを選択します
  3. 次を入力します。
Product NameToken Top-Up PackDescriptionInstantly add 5 million tokens to your NeuralAPI balance.Price19.00CurrencyUSD
2

Attach the token credit

  1. Entitlementsセクションで、Creditsの横にあるAttachをクリックします
  2. API Tokensを選択します
  3. Credits issued5000000に設定します
  4. Import Default Credit Settings無効にします — デフォルトの30日間の有効期限を上書きします
  5. Credit Expiry365 daysに設定します
  6. 商品を保存します
商品IDをコピーします。
追加購入の有効期限を長くする理由は何でしょうか。サブスクリプションのクレジットはサイクルに合わせて30日ごとにリセットされます。一方、追加購入は前払い購入です。顧客は$19を先に支払っているため、トークンが1か月を超えて有効であることを当然期待します。365日という期間は、OpenAI、AWS、Anthropicの実際のプリペイドクレジットの仕組みに合致し、顧客による無期限の蓄積を防いで責任範囲も制限できます。
追加購入パックを設定しました。購入すると5,000,000トークンが付与され、365日間有効です。

Step 5:バックエンドを構築する

次に、サブスクリプションのcheckout、追加購入のcheckout、トークン請求を伴う実際のOpenAI completion、残高照会、クレジットwebhookイベントを処理するExpressサーバーを構築します。
1

Set up your project

tsconfig.jsonを作成します。
tsconfig.json
package.jsonのscriptsを更新します。
package.json
2

Set up environment variables

前の手順で取得した認証情報とIDを使って.envを作成します。
.env
.envをバージョン管理にコミットしないでください。すぐに.gitignoreへ追加します。
webhookエンドポイントを登録した後、Step 7でDODO_PAYMENTS_WEBHOOK_KEYを入力します。
3

Implement the server

src/server.tsを作成します。
バックエンドが完成しました。サブスクリプションcheckout、追加購入checkout、メーターによるトークン請求付きOpenAI completion、残高照会、署名検証済みwebhookハンドラーを備えています。
@dodopayments/ingestion-blueprintsには、usageEvents.ingest呼び出しを自動化する、そのまま使えるトラッカーが含まれています。LLM BlueprintAPI gatewayobject storagestreamstime-rangeの使用量に対応しています。
4

A note on how deductions actually happen

明示的な「Nクレジットを差し引く」呼び出しがないことに気付いたかもしれません。これは意図した設計です。
  1. ハンドラーがOpenAIを呼び出し、usage.total_tokens(例:1532)を取得します。
  2. 1件の使用量イベントを取り込みます:event_name: api.tokens_usedmetadata: { tokens: 1532 }
  3. Token Usage Meterが顧客ごとにイベントを集計します。
  4. メーターがBill usage in Credits付きでAPI Tokensクレジットに接続されているため、Dodo Paymentsは顧客の最も古い有効期限未到来の付与分からFIFOで1,532クレジットを差し引きます。
  5. 超過利用が有効で顧客が0未満になった場合、不足分が記録され、次回請求書で請求されます。
これらはすべてメーターが処理します。コードで行うのはイベントの取り込みだけです。

Step 6:デモフロントエンドを追加する

ブラウザーで全フローをテストするため、public/index.htmlを作成します。顧客IDをlocalStorageに保存することで、subscribe → generate → top-upが同じIDを共有し、ログイン済みアプリを再現します。

Step 7:webhookを接続する

webhookを使うと、サーバーは残高の変化に反応できます。顧客が残高0に達する前に「残りわずか」メールを送信するために使用します。
1

Expose your local server

webhookには公開URLが必要です。ローカル開発ではngrokなどのトンネルを使用します。
https://...ngrok-free.app URLをコピーします。
2

Register the webhook in Dodo Payments

  1. ダッシュボードでDevelopers → Webhooks → Add Endpointに移動します
  2. URLhttps://your-tunnel.ngrok-free.app/webhooks/dodo
  3. 最低限、次のイベントを購読します。
    • credit.added
    • credit.deducted
    • credit.overage_charged
  4. 保存してSigning Secretをコピーします
  5. .envDODO_PAYMENTS_WEBHOOK_KEYとして貼り付け、npm run devを再起動します
SDKのdodo.webhooks.unwrap()は、署名シークレットを使ってwebhook-idwebhook-timestampwebhook-signatureヘッダーを検証します。HMAC検証を自作する必要はありません。すべきでもありません。Dodo PaymentsはStandard Webhooksを使用し、本文だけでなくid.timestamp.bodyに署名するためです。

Step 8:フロー全体をテストする

1

Subscribe a test customer

  1. npm run devを実行します
  2. http://localhost:3000を開きます
  3. Pro Planを選択し、テスト用メールアドレスと名前を入力してGet Checkout Linkをクリックし、テストカード情報でcheckoutを完了します
  4. ダッシュボードでCustomers → 最新の顧客に移動し、cus_... IDをコピーします
  5. デモの「Logged-in customer ID」フィールドに貼り付け、Saveをクリックします
顧客には40,000,000トークンが付与されているはずです。Refresh Balanceをクリックして確認します。
2

Generate a real AI response

プロンプトを入力してGenerateをクリックします。サーバーはOpenAIを呼び出し、実際のtotal_tokensを取得し、使用量イベントを取り込んでレスポンスを返します。
使用量イベントは、約1分ごとにバックグラウンドワーカーで処理されます。残高はすぐには減少しません。30〜90秒待ってから、もう一度Refresh Balanceをクリックしてください。最初の更新で変化がなくても、壊れていると判断しないでください。
3

Test the top-up flow

Buy 5M Tokens — $19をクリックしてcheckoutを完了します。支払いが成功したら残高を更新します。5,000,000トークン増えているはずです。サーバーログにはcredit.addedイベントが表示されます。

トラブルシューティング

考えられる原因:
  • メーターのイベント名が送信しているevent_nameと一致していない(api.tokens_usedは大文字と小文字を区別します)
  • メーターが商品上のAPI Tokensクレジットにリンクされていない — 商品のメーター設定でBill usage in Creditsがオンか確認します
  • metadata.tokensキーがメーターの「Over Property」フィールドと一致していない
  • 顧客の付与分が期限切れになっている(顧客のクレジット履歴を確認します)
確認事項:
  1. Products → Meters:メーターを開き、商品への関連付けにリンク済みクレジット名が表示されていることを確認します
  2. メーターのEventsタブ:差し引き前でも取り込まれたイベントが表示されます
  3. Customers → [Customer] → Credits:1〜2分以内に台帳エントリが表示されます
考えられる原因:
  • 顧客がまだcheckoutを完了していない — クレジットは支払い成功後にのみ付与されます
  • 間違ったcustomer_idで照会している(自分のDB IDではなく、ダッシュボードのcus_... IDを使用します)
  • .env内のCREDIT_ENTITLEMENT_IDが、商品に関連付けたクレジットと一致していない
確認事項: Customers → [Customer] → Creditsを開きます。クレジットが表示されない場合、商品エンタイトルメントが関連付けられていないか、支払いが完了していません。
考えられる原因:
  • Pro商品へのクレジット関連付けで超過利用が有効になっていない(クレジットレベルの設定はデフォルトにすぎません)
  • 顧客が実際にはProではなくStarterを利用している
  • 超過利用の上限が0に設定されている
確認事項: Pro → Entitlements → Creditsを編集し、Allow Overageがオンで、Price Per Unit0.000005(= 100万トークンあたり$5)であることを確認します。先頭のゼロを再確認してください。このフィールドは1Kあたりではなく、トークン単位の価格を受け取ります。
考えられる原因:
  • 本文解析の順序: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

全プランと追加購入パックで共有する、30日間の有効期限付き再利用可能なAPI Tokensクレジット

Tiered Plans, One Credit

クレジットを重複させず、商品ごとにStarter(10M、ハードリミット)とPro(40M + 超過利用)を設定

One-Time Top-Up Pack

顧客はサブスクリプションを変更せず、$19で5Mトークンを追加購入可能

Auto-Deduction via Meter

実際のOpenAIトークン数をイベントとして取り込み、メーターが手動追跡なしでFIFOによりクレジットを差し引きます

Live Balance API

SDK経由のリアルタイム残高により、アクセス制御、使用量表示、アプリ内での顧客への警告が可能です

Verified Webhook Pipeline

クレジット台帳イベント(credit.addedcredit.deductedcredit.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.cancelled webhookを監視してサブスクリプション状態に基づき/api/generateを制御するか、(b) Dodoの台帳APIを呼び出し、解約時に未使用のプランクレジットを差し引き、追加購入クレジットは維持します。
  • Usage Billingダッシュボードを監視して、メーターの異常を早期に検出します。

Credit-Based Billing Reference

CBBの完全なドキュメント:ロールオーバー、超過利用モード、台帳管理、すべてのAPIエンドポイント。

Credit Webhook Events

サーバーが受信する可能性のあるすべてのクレジットイベントのペイロードスキーマ。
最終更新日 2026年7月31日