Skip to main content
コーディングエージェントに統合を作成させるには、Dodo Agent Plugin をインストールします。これにより、Dodo Payments のスキルと MCP サーバーが Claude Code、Codex CLI、Cursor、VS Code / GitHub Copilot、Kiro、OpenCode に追加されます。
NeuralAPI を構築します。これは段階制の AI API で、各サブスクリプションプランに毎月のトークンクレジットが含まれます。残高が少なくなった顧客は追加購入パックを購入でき、バックエンドは各 OpenAI リクエストで使用されたトークン数を報告します。Dodo Payments はその数を顧客の残高から差し引きます。
このチュートリアルでは Node.js、Express、OpenAI SDK を使用します。Dodo Payments の概念(クレジット、メーター、webhook)は、どのフレームワークや AI プロバイダーでも同じように機能します。
完了すると、次の方法がわかります。
  • トークン用のカスタムクレジット entitlement と、それを差し引くメーターを作成する。
  • 超過使用を許可する場合と許可しない場合の両方で、サブスクリプションプランおよび一回限りの追加購入商品にクレジットを割り当てる。
  • Dodo Payments 経由でトークンを請求するエンドポイントから OpenAI を呼び出す。
  • SDK で顧客の現在のクレジット残高を読み取る。
  • webhook 署名を検証し、Dodo Payments のクレジットイベントを振り分ける。

構築するもの

NeuralAPI は次の 3 つの商品を販売します。 開始する前に、次のものが必要です。
  • Dodo Payments アカウント。すべてテストモードで構築します。
  • OpenAI API key。
  • Node.js 22 以降、および TypeScript と Node.js の基本的な知識。

Step 1: トークンクレジット entitlement を作成する

両方のプランと追加購入パックで共有するクレジット entitlement を作成します。これにより、NeuralAPI が販売するトークン単位を定義します。
作成したクレジット entitlement が表示されたクレジット一覧ページ

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 Name: API TokensCredit Type: Custom UnitUnit Name: tokenDefine Precision: 0。トークン数は整数です。Credit Expiry: 30 days。クレジットは発行から 30 日後に期限切れになります。これは毎月の請求サイクルに一致します。
クレジットを作成した後は、精度を変更できません。トークン数には 0 を使用します。
3

Skip Overage at the Credit Level

クレジットでは超過使用を 無効 のままにします。各商品にクレジットを割り当てる際にプランごとに設定するため、Starter plan では残高が 0 で使用を停止し、Pro plan では超過使用を許可できます。
クレジットの超過使用設定はデフォルト値です。各商品への割り当てで上書きでき、Step 3 では Pro plan に対して上書きします。
4

Save and Copy the Credit ID

Create Credit をクリックします。保存したクレジットを開き、ID をコピーします。ID は cde_ で始まります。
API Tokens クレジット entitlement の準備ができました。次に、使用量イベントがクレジットを差し引くようにメーターを作成します。

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

メーターは、受信した使用量イベントを集計します。メーターをクレジットにリンクすると、集計された使用量が顧客のクレジット残高から差し引かれます。Step 3 でプラン商品を作成する際にメーターを割り当てるため、プラン商品より先にメーターを作成します。
1

Open the Meters Section

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

Configure the Meter

次の値を入力します。Meter Name: Token Usage MeterEvent Name: api.tokens_used。これはアプリが送信する event_name と一致する必要があります。Aggregation Type: Sum。各イベントのトークン数を合計します。Over Property: tokens。値を合計する metadata key です。Measurement Unit: tokens
イベント名では大文字と小文字が区別されます。api.tokens_used と Api.Tokens.Used は異なるイベントです。メーターは作成後に編集できないため、確定する前にすべての値を確認してください。
メーターを作成します。商品に割り当てるときは、名前で選択します。
メーターが作成されました。次に、各プラン商品でメーターをクレジットにリンクします。

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

両方のプランを、通常の Subscription ではなく Usage Based Billing の pricing type で作成します。メーターは Usage Based Billing 商品に割り当てられ、顧客が API を呼び出すとメーターがクレジットを差し引きます。Usage Based Billing 商品でも定期的な基本料金($29 または $99)が請求され、その上の使用量はクレジットで請求されます。
Usage Based Billing の pricing 設定

Usage Based Billing pricing type with meter configuration.

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

1

Create the Starter Product

  1. Products に移動し、Add Product をクリックします。
  2. Pricing Type で Usage Based Billing を選択します。
  3. 次の値を入力します。
Product Name: NeuralAPI StarterDescription: 10 million API tokens per month. Perfect for individual developers and small projects.Price: 29.00。これは定期的な基本料金で、使用量がなくても毎月請求されます。Repeat payment every: 1 monthCurrency: USD
2

Attach the Meter

Select meter セクションで + をクリックし、Token Usage Meter を追加します。次にメーターを設定します。
  1. Bill usage in credits をオンにします。
  2. Select credit: API Tokens
  3. Meter units per credit: 1。イベント内の各トークンにつき 1 クレジットを差し引きます。
  4. Free Threshold: 0。無料しきい値は、メーターが金額で請求する場合にのみ適用されます。クレジットで請求する場合は、すべての単位が残高から差し引かれます。
Bill usage in Credits が有効で API Tokens が選択されたメーター

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 cycle: 10000000Import Default Credit Settings: オン。クレジット entitlement の 30 日の有効期限を使用します。Allow Overage: オフ。Step 1 のデフォルト設定により超過使用が無効になり、Starter の顧客は残高が 0 で停止します。
サイクルごとの付与量と超過使用設定を含むクレジット設定フォーム

Configure credit issuance per cycle on the UBB product.

商品を保存し、ID をコピーします。ID は pdt_ で始まります。
Starter Plan: 月額 $29 の基本料金、サイクルごとに 10M トークン、残高が 0 で停止し、メーター経由で差し引かれます。

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

1

Create the Pro Product

次の値を使用して Starter と同じ手順を進めます。Product Name: NeuralAPI ProDescription: 40 million API tokens per month with overage. Built for production applications.Price: 99.00Repeat payment every: 1 monthCurrency: USD
2

Attach the Meter

Starter と同じようにメーターを設定します。Token Usage Meter を追加し、Bill usage in credits をオンにして、API Tokens を選択します。Meter units per credit は 1、Free Threshold は 0 に設定します。
3

Configure Credit Issuance with Overage

今回は超過使用を有効にして、クレジットの付与を設定します。Credits issued per billing cycle: 40000000Import Default Credit Settings: オフ。この商品で超過使用を設定できるようにします。Allow Overage: オンPrice Per Unit: 0.000005 USD/トークン。これは 1K トークンあたり $0.005、1M トークンあたり $5 に相当します。プランの実質的なトークン単価より高く、超過使用を抑制します。Overage Behavior: Bill overage at billing。超過使用分は次回の請求書で請求され、その後残高がリセットされます。商品を保存し、ID をコピーします。
Pro Plan: 月額 $99 の基本料金、サイクルごとに 40M トークン、1K トークンあたり $0.005 の超過使用料金で、メーター経由で差し引かれます。

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

追加購入パックは、既存顧客の残高に 5,000,000 トークンを追加する一回限りの購入です。
Single Payment が選択された商品 pricing セクション

One-time pricing selected for a credit product.

1

Create a One-Time Product

  1. Products に移動し、Add Product をクリックします。
  2. Pricing Type で One Time を選択します。
  3. 次の値を入力します。
Product Name: Token Top-Up PackDescription: Add 5 million tokens to your NeuralAPI balance.Price: 19.00Currency: USD
2

Attach the Token Credit

  1. Entitlements セクションで、Credits の横にある Attach をクリックします。
  2. API Tokens を選択します。
  3. No of credits issued を 5000000 に設定します。
  4. Import Default Credit Settings をオフにして、デフォルトの 30 日の有効期限を上書きします。
  5. Credit Expiry を Custom に設定し、365 日と入力します。
  6. 商品を保存します。
商品 ID をコピーします。
トップアップの有効期限を長くする理由は?サブスクリプションのクレジットは請求サイクルに合わせて30日で失効します。トップアップは前払い購入です。顧客は$19を先に支払い、トークンが1か月より長く使えることを期待します。365日の有効期限は、OpenAIやAnthropicでのプリペイドAPIクレジットの仕組みに合っています。購入したクレジットは購入から1年後に失効し、同時に顧客がクレジットを無期限に蓄積できないよう、責任範囲にも上限を設けられます。
Top-Up Pack が設定されました。購入すると 5,000,000 トークンが付与され、365 日間有効になります。

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

Express サーバーを構築します。サブスクリプションと追加購入の checkout を作成し、OpenAI を呼び出してトークンを請求し、残高を読み取り、クレジット webhook イベントを受信します。
1

Set Up Your Project

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

Set Up Environment Variables

Developer → API Keys から取得したテストモード API key と、前の手順で取得した ID を使用して .env を作成します。
.env
.env をバージョン管理にコミットしないでください。最初のコミット前に .gitignore に追加します。
webhook endpoint を登録した後、Step 7 で DODO_PAYMENTS_WEBHOOK_KEY を入力します。
3

Implement the Server

src/server.tsを作成します。completion endpointはOpenAIのgpt-6-lunaモデルを呼び出します。このモデルは大量のリクエストに適しています。package.jsonタブには依存関係の一覧が表示されます。
バックエンドの準備は完了しました。サブスクリプションのチェックアウト、トップアップのチェックアウト、従量制トークン課金に対応したOpenAI completion、残高の読み取り、署名検証済みwebhook handlerが実装されています。
@dodopayments/ingestion-blueprintsには、usageEvents.ingestの呼び出しを代行するtrackerが用意されています。LLM Blueprint、API gateway、object storage、streams、time-rangeの使用量に対応しています。
4

How Deductions Happen

サーバーが「Nクレジットを差し引く」endpointを呼び出すことはありません。差し引きを行うのはmeterです。
  1. handlerがOpenAIを呼び出し、usage.total_tokensを読み取ります。たとえば1532です。
  2. event_name: api.tokens_usedとmetadata: { tokens: 1532 }を使って、1件のusage eventを取り込みます。
  3. Token Usage Meterが顧客ごとにイベントを集計します。バックグラウンドworkerが新しいイベントを毎分処理します。
  4. meterがBill usage in creditsを通じてAPI Tokensクレジットに課金するため、Dodo Paymentsは1532クレジットを差し引きます。差し引きは、顧客のgrantのうち有効期限が最も早いものから開始されます(FIFO)。
  5. overageが有効で残高が不足した場合、未払い分が記録され、次回のinvoiceで請求されます。
コードが行うのはイベントの取り込みだけです。

Step 6: Demo Frontendを追加する

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

Step 7: Webhookを接続する

Webhooksを使うと、サーバーは残高の変化に応答できます。たとえば、残高が少なくなった顧客にメールを送信できます。
1

Expose Your Local Server

Webhooksには公開URLが必要です。ローカル開発では、ngrokなどのトンネルを使用します。
HTTPS forwarding URLをコピーします。URLの末尾はngrok-free.appです。
2

Register the Webhook in Dodo Payments

  1. dashboardでDeveloper → Webhooksに移動し、Add endpointをクリックします。
  2. 自分のトンネルホストを使い、URL https://your-tunnel.ngrok-free.app/webhooks/dodoを入力します。
  3. 少なくとも次のイベントを選択します。
    • credit.added
    • credit.deducted
    • credit.overage_charged
  4. Create endpointをクリックし、endpointのOverviewタブからsigning secretをコピーします。
  5. .envにDODO_PAYMENTS_WEBHOOK_KEYとして貼り付け、その後npm run devを再起動します。
SDKのdodo.webhooks.unwrap()は、signing secretを使ってwebhook-id、webhook-timestamp、webhook-signatureのheadersを検証し、payloadを解析します。独自のHMAC checkは実装しないでください。Dodo PaymentsはStandard Webhooksに従い、bodyだけではなくid.timestamp.bodyに署名します。

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

1

Subscribe a Test Customer

  1. npm run devを実行します。
  2. http://localhost:3000を開きます。
  3. Proを選択し、テスト用のメールアドレスと名前を入力して、Get Checkout Linkをクリックします。test card detailsを使ってチェックアウトを完了します。
  4. dashboardでCustomersに移動し、最新の顧客を開いてIDをコピーします。IDはcus_で始まります。
  5. IDをdemoのLogged-in customer IDフィールドに貼り付け、Saveをクリックします。
顧客には40,000,000トークンが付与されています。Refresh Balanceをクリックして確認します。
2

Generate an AI Response

プロンプトを入力し、Generateをクリックします。サーバーがOpenAIを呼び出し、実際のtotal_tokensを読み取り、usage eventを取り込んで応答を返します。
バックグラウンドworkerはusage eventを毎分処理するため、残高はすぐには減少しません。1~2分待ってから、もう一度Refresh Balanceをクリックします。最初の更新で残高が変わらなくても、meteringが失敗したとは限りません。
3

Test the Top-Up Flow

Buy 5M Tokens — $19をクリックしてチェックアウトを完了します。支払いが成功したら残高を更新します。残高が5,000,000トークン増加し、server logにcredit.added eventが表示されます。

トラブルシューティング

考えられる原因:
  • meterのイベント名が、送信するevent_nameと一致していません。api.tokens_usedは大文字と小文字を区別します。
  • meterがproductのAPI Tokens creditにリンクされていません。productのmeter configurationを開き、Bill usage in creditsが有効であることを確認します。
  • metadata.tokens keyがmeterのOver Propertyと一致していません。
  • 顧客のgrantが失効しています。顧客のcredit historyを確認します。
確認事項:
  1. Products → Metersでmeterを開き、product attachmentにリンクされたcredit nameが表示されていることを確認します。
  2. meterのEventsタブを開きます。取り込まれたイベントは差し引きが行われる前でもここに表示されます。
  3. Customersで顧客を開き、Creditsタブを選択します。ledger entryは1~2分以内に表示されます。
考えられる原因:
  • 顧客がチェックアウトを完了していません。クレジットは支払いが成功した後にのみ付与されます。
  • 間違ったcustomer_idでクエリしています。自分のdatabaseのIDではなく、dashboardに表示されるcus_で始まるIDを使用します。
  • .env内のCREDIT_ENTITLEMENT_IDが、productに紐付けられたcreditと一致していません。
確認事項: Customersで顧客を開き、Creditsタブを選択します。クレジットが表示されない場合、creditがproductに紐付けられていないか、支払いが完了していません。
考えられる原因:
  • Pro product’s credit attachmentでoverageが有効になっていません。credit側の設定はデフォルト値にすぎません。
  • 顧客がProではなくStarterを利用しています。
  • Overage Limitが0に設定されています。
確認事項: Pro productを編集し、Entitlementsでcreditを開きます。Allow Overageが有効で、Price Per Unitが0.000005(100万トークンあたり$5)であることを確認します。先頭のゼロに注意してください。このフィールドは1Kトークンあたりではなく、1トークンあたりの価格を受け取ります。
考えられる原因:
  • body parsingの順序に問題があります。express.json()が/webhooks/dodoに対して、express.raw()より先に実行されました。SDKには解析済みJSONではなく、リクエストのraw bytesが必要です。
  • DODO_PAYMENTS_WEBHOOK_KEYに誤ったsigning secretが設定されています。
  • reverse proxyがrequest headersを書き換えています。
確認事項: app.use('/webhooks/dodo', express.raw(...))の行が、server.ts内でapp.use(express.json())より前にあることを確認します。

サポートが必要ですか?

おめでとうございます!NeuralAPIのクレジットベース課金を構築しました

NeuralAPIはチェックアウトから差し引きまで、クレジットで課金できるようになりました。

Token Credit Entitlement

両方のプランとトップアップパックで共有される、30日間の有効期限を持つ再利用可能なAPI Tokens creditです。

Tiered Plans, One Credit

Starter(10Mトークン、ハードリミット)とPro(40Mトークンとoverage)を、creditを重複作成せずproductごとに設定しています。

One-Time Top-Up Pack

顧客はサブスクリプションを変更せずに、5Mトークンを$19で追加できます。

Deduction Through a Meter

実際のOpenAI token countがイベントとして取り込まれ、meterが手動の追跡なしでFIFO方式によりクレジットを差し引きます。

Live Balance API

SDKを通じて読み取った現在の残高を使い、アプリでアクセスを制御したり、使用量を表示したり、顧客に警告したりできます。

Verified Webhook Pipeline

credit ledger event(credit.added、credit.deducted、credit.overage_charged)は、SDKのStandard Webhooks helperで署名を検証するhandlerに送られます。
本番環境に移行しますか? 次の点を強化してください。
  • /credits/:customerIdと/api/generateにauthenticationを追加します。 このままでは、誰でも任意のcustomer IDで呼び出せます。ユーザーを認証し、サーバー上でcustomer IDを取得してください。
  • 安定したevent_id valueを使用します。 例ではDate.now()とランダムな文字列を使用しています。本番環境ではリクエストIDを使用してretryをidempotentにします。Dodo Paymentsは、すでに取り込んだevent_idのイベントを無視します。
  • customer-to-user mappingを保存します。 初回チェックアウト後にcustomer_idをdatabaseに保存し、ユーザーが手動で貼り付けなくても済むようにします。
  • サブスクリプション終了時の動作を決めます。 プランのクレジットは付与から30日後に失効するまで顧客のledgerに残り、トップアップクレジットは365日間有効です。チュートリアルの/api/generateは残高だけを確認し、サブスクリプションのstatusは確認しません。そのため、キャンセルされた顧客も残りのトークンを使用できます。これは顧客にとって親切なデフォルトです。より厳格にアクセスを制御するには、(a) subscription.cancelled webhookを監視してサブスクリプションのstatusに基づいて/api/generateを制御するか、(b)キャンセル時にledger APIで未使用のプランクレジットをdebitします。debitは有効期限が最も早いgrantから行われるため、365日間有効なトップアップクレジットより先に30日間のプランクレジットが使われます。
  • Usage Billing dashboardを監視して、meteringの異常を早期に検出します。

Credit-Based Billing Reference

Rollover、overage modes、ledger management、すべてのcredit API endpointに対応しています。

Credit Webhook Events

サーバーが受信できるすべてのcredit eventのpayload schemaです。
最終更新日 2026年9月26日