- トークン用のカスタムクレジット 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 が販売するトークン単位を定義します。
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 UnitUnit Name: tokenDefine Precision: 0。トークン数は整数です。Credit Expiry: 30 days。クレジットは発行から 30 日後に期限切れになります。これは毎月の請求サイクルに一致します。Skip Overage at the Credit Level
Save and Copy the Credit ID
cde_ で始まります。API Tokens クレジット entitlement の準備ができました。次に、使用量イベントがクレジットを差し引くようにメーターを作成します。Step 2: トークン使用量用のメーターを作成する
メーターは、受信した使用量イベントを集計します。メーターをクレジットにリンクすると、集計された使用量が顧客のクレジット残高から差し引かれます。Step 3 でプラン商品を作成する際にメーターを割り当てるため、プラン商品より先にメーターを作成します。Open the Meters Section
- ダッシュボードのサイドバーで Products → Meters に移動します。
- Create Meter をクリックします。
Configure the Meter
Token Usage MeterEvent Name: api.tokens_used。これはアプリが送信する event_name と一致する必要があります。Aggregation Type: Sum。各イベントのトークン数を合計します。Over Property: tokens。値を合計する metadata key です。Measurement Unit: tokensメーターを作成します。商品に割り当てるときは、名前で選択します。Step 3: プラン商品を作成する
両方のプランを、通常の Subscription ではなく Usage Based Billing の pricing type で作成します。メーターは Usage Based Billing 商品に割り当てられ、顧客が API を呼び出すとメーターがクレジットを差し引きます。Usage Based Billing 商品でも定期的な基本料金($29 または $99)が請求され、その上の使用量はクレジットで請求されます。
Usage Based Billing pricing type with meter configuration.
Starter Plan ($29/月 — 10M トークン、超過使用なし)
Create the Starter Product
- Products に移動し、Add Product をクリックします。
- Pricing Type で Usage Based Billing を選択します。
- 次の値を入力します。
NeuralAPI StarterDescription: 10 million API tokens per month. Perfect for individual developers and small projects.Price: 29.00。これは定期的な基本料金で、使用量がなくても毎月請求されます。Repeat payment every: 1 monthCurrency: USDAttach the Meter
Token Usage Meter を追加します。次にメーターを設定します。- Bill usage in credits をオンにします。
- Select credit:
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
10000000Import Default Credit Settings: オン。クレジット entitlement の 30 日の有効期限を使用します。Allow Overage: オフ。Step 1 のデフォルト設定により超過使用が無効になり、Starter の顧客は残高が 0 で停止します。
Configure credit issuance per cycle on the UBB product.
pdt_ で始まります。Pro Plan ($99/月 — 40M トークン、超過使用を有効化)
Create the Pro Product
NeuralAPI ProDescription: 40 million API tokens per month with overage. Built for production applications.Price: 99.00Repeat payment every: 1 monthCurrency: 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 トークンあたり $0.005、1M トークンあたり $5 に相当します。プランの実質的なトークン単価より高く、超過使用を抑制します。Overage Behavior: Bill overage at billing。超過使用分は次回の請求書で請求され、その後残高がリセットされます。商品を保存し、ID をコピーします。Step 4: トークン追加購入パックを作成する
追加購入パックは、既存顧客の残高に 5,000,000 トークンを追加する一回限りの購入です。
One-time pricing selected for a credit product.
Create a One-Time Product
- Products に移動し、Add Product をクリックします。
- Pricing Type で One Time を選択します。
- 次の値を入力します。
Token Top-Up PackDescription: Add 5 million tokens to your NeuralAPI balance.Price: 19.00Currency: USDAttach the Token Credit
- Entitlements セクションで、Credits の横にある Attach をクリックします。
API Tokensを選択します。- No of credits issued を
5000000に設定します。 - Import Default Credit Settings をオフにして、デフォルトの 30 日の有効期限を上書きします。
- Credit Expiry を Custom に設定し、
365日と入力します。 - 商品を保存します。
Step 5: バックエンドを構築する
Express サーバーを構築します。サブスクリプションと追加購入の checkout を作成し、OpenAI を呼び出してトークンを請求し、残高を読み取り、クレジット webhook イベントを受信します。Set Up Your Project
tsconfig.json を作成します。package.json の scripts を更新します。Set Up Environment Variables
.env を作成します。DODO_PAYMENTS_WEBHOOK_KEY を入力します。Implement the Server
src/server.tsを作成します。completion endpointはOpenAIのgpt-6-lunaモデルを呼び出します。このモデルは大量のリクエストに適しています。package.jsonタブには依存関係の一覧が表示されます。How Deductions Happen
- handlerがOpenAIを呼び出し、
usage.total_tokensを読み取ります。たとえば1532です。 event_name: api.tokens_usedとmetadata: { tokens: 1532 }を使って、1件のusage eventを取り込みます。Token Usage Meterが顧客ごとにイベントを集計します。バックグラウンドworkerが新しいイベントを毎分処理します。- meterがBill usage in creditsを通じて
API Tokensクレジットに課金するため、Dodo Paymentsは1532クレジットを差し引きます。差し引きは、顧客のgrantのうち有効期限が最も早いものから開始されます(FIFO)。 - overageが有効で残高が不足した場合、未払い分が記録され、次回のinvoiceで請求されます。
Step 6: Demo Frontendを追加する
ブラウザで各フローをテストするため、public/index.htmlを作成します。このページは顧客IDをlocalStorageに保存します。ログイン済みアプリと同様に、subscribe、generate、top-upで同じidentityが共有されます。
Step 7: Webhookを接続する
Webhooksを使うと、サーバーは残高の変化に応答できます。たとえば、残高が少なくなった顧客にメールを送信できます。Expose Your Local Server
ngrok-free.appです。Register the Webhook in Dodo Payments
- dashboardでDeveloper → Webhooksに移動し、Add endpointをクリックします。
- 自分のトンネルホストを使い、URL
https://your-tunnel.ngrok-free.app/webhooks/dodoを入力します。 - 少なくとも次のイベントを選択します。
credit.addedcredit.deductedcredit.overage_charged
- Create endpointをクリックし、endpointのOverviewタブからsigning secretをコピーします。
.envにDODO_PAYMENTS_WEBHOOK_KEYとして貼り付け、その後npm run devを再起動します。
Step 8: フロー全体をテストする
Subscribe a Test Customer
npm run devを実行します。http://localhost:3000を開きます。- Proを選択し、テスト用のメールアドレスと名前を入力して、Get Checkout Linkをクリックします。test card detailsを使ってチェックアウトを完了します。
- dashboardでCustomersに移動し、最新の顧客を開いてIDをコピーします。IDは
cus_で始まります。 - IDをdemoのLogged-in customer IDフィールドに貼り付け、Saveをクリックします。
Generate an AI Response
total_tokensを読み取り、usage eventを取り込んで応答を返します。Test the Top-Up Flow
credit.added eventが表示されます。トラブルシューティング
Credits not deducting after usage events
Credits not deducting after usage events
- meterのイベント名が、送信する
event_nameと一致していません。api.tokens_usedは大文字と小文字を区別します。 - meterがproductの
API Tokenscreditにリンクされていません。productのmeter configurationを開き、Bill usage in creditsが有効であることを確認します。 metadata.tokenskeyがmeterのOver Propertyと一致していません。- 顧客のgrantが失効しています。顧客のcredit historyを確認します。
- Products → Metersでmeterを開き、product attachmentにリンクされたcredit nameが表示されていることを確認します。
- meterのEventsタブを開きます。取り込まれたイベントは差し引きが行われる前でもここに表示されます。
- Customersで顧客を開き、Creditsタブを選択します。ledger entryは1~2分以内に表示されます。
Balance always shows 0 or 'customer not found'
Balance always shows 0 or 'customer not found'
- 顧客がチェックアウトを完了していません。クレジットは支払いが成功した後にのみ付与されます。
- 間違った
customer_idでクエリしています。自分のdatabaseのIDではなく、dashboardに表示されるcus_で始まるIDを使用します。 .env内のCREDIT_ENTITLEMENT_IDが、productに紐付けられたcreditと一致していません。
Overage not working for Pro plan customers
Overage not working for Pro plan customers
- Pro product’s credit attachmentでoverageが有効になっていません。credit側の設定はデフォルト値にすぎません。
- 顧客がProではなくStarterを利用しています。
- Overage Limitが0に設定されています。
0.000005(100万トークンあたり$5)であることを確認します。先頭のゼロに注意してください。このフィールドは1Kトークンあたりではなく、1トークンあたりの価格を受け取ります。Webhook verification failed in logs
Webhook verification failed in logs
- 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
API Tokens creditです。Tiered Plans, One Credit
One-Time Top-Up Pack
Deduction Through a Meter
Live Balance API
Verified Webhook Pipeline
credit.added、credit.deducted、credit.overage_charged)は、SDKのStandard Webhooks helperで署名を検証するhandlerに送られます。/credits/:customerIdと/api/generateにauthenticationを追加します。 このままでは、誰でも任意のcustomer IDで呼び出せます。ユーザーを認証し、サーバー上でcustomer IDを取得してください。- 安定した
event_idvalueを使用します。 例ではDate.now()とランダムな文字列を使用しています。本番環境ではリクエストIDを使用してretryをidempotentにします。Dodo Paymentsは、すでに取り込んだevent_idのイベントを無視します。 - customer-to-user mappingを保存します。 初回チェックアウト後に
customer_idをdatabaseに保存し、ユーザーが手動で貼り付けなくても済むようにします。 - サブスクリプション終了時の動作を決めます。 プランのクレジットは付与から30日後に失効するまで顧客のledgerに残り、トップアップクレジットは365日間有効です。チュートリアルの
/api/generateは残高だけを確認し、サブスクリプションのstatusは確認しません。そのため、キャンセルされた顧客も残りのトークンを使用できます。これは顧客にとって親切なデフォルトです。より厳格にアクセスを制御するには、(a)subscription.cancelledwebhookを監視してサブスクリプションのstatusに基づいて/api/generateを制御するか、(b)キャンセル時にledger APIで未使用のプランクレジットをdebitします。debitは有効期限が最も早いgrantから行われるため、365日間有効なトップアップクレジットより先に30日間のプランクレジットが使われます。 - Usage Billing dashboardを監視して、meteringの異常を早期に検出します。