- 为 tokens 创建 custom credit entitlement,并创建从中扣除 credits 的 meter。
- 将 credits 附加到订阅计划(可配置是否允许 overage)以及一次性充值产品。
- 从一个通过 Dodo Payments 对 tokens 计费的 endpoint 调用 OpenAI。
- 使用 SDK 读取客户的实时 credit balance。
- 验证 webhook signatures,并路由 Dodo Payments credit events。
我们要构建的内容
NeuralAPI 销售三种产品:- 一个 Dodo Payments account。请在 test mode 中完成所有操作。
- 一个 OpenAI API key。
- Node.js 22 或更高版本,以及 TypeScript 和 Node.js 的基本使用经验。
步骤 1:创建 Token Credit Entitlement
创建两个计划和充值包共用的 credit entitlement。它定义了 NeuralAPI 销售的 token 单位。
The Credits tab under Products shows all your credit entitlements.
Navigate to Credits
- 登录 Dodo Payments dashboard。
- 在侧边栏中点击 Products。
- 选择 Credits 标签页。
- 点击 Create Credit。
Configure the Credit Unit
API TokensCredit Type:Custom UnitUnit Name:tokenDefine Precision:0。Token 数量为整数。Credit Expiry:30 days。Credits 会在发放 30 天后过期,这与每月计费周期一致。Skip Overage at the Credit Level
Save and Copy the Credit ID
cde_ 开头。API Tokens credit entitlement 已准备就绪。接下来创建 meter,使 usage events 能够扣除 credits。步骤 2:创建 Token Usage Meter
Meter 会聚合传入的 usage events。当你将它链接到 credit 后,聚合的 usage 会从客户的 credit balance 中扣除。请在创建计划产品之前创建 meter,因为你需要在步骤 3 创建产品时附加它。Open the Meters Section
- 在 dashboard 侧边栏中前往 Products → Meters。
- 点击 Create Meter。
Configure the Meter
Token Usage MeterEvent Name:api.tokens_used。它必须与应用发送的 event_name 匹配。Aggregation Type:Sum,用于累加每个 event 中的 token count。Over Property:tokens,即要汇总其值的 metadata key。Measurement Unit:tokens创建 meter。将它附加到产品时,你会按名称选择它。步骤 3:创建计划产品
使用 Usage Based Billing pricing type 创建两个计划,而不是普通的 Subscription。Meter 只能附加到 Usage Based Billing products,并且正是 meter 在客户调用 API 时扣除 credits。Usage Based Billing product 仍会收取 recurring base fee($29 或 $99),其额外 usage 则以 credits 计费。
Usage Based Billing pricing type with meter configuration.
Starter Plan($29/月 — 10M Tokens,不允许 Overage)
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。这是 recurring base fee,即使尚未产生任何 usage,也会每月收取。Repeat payment every:1 monthCurrency:USDAttach the Meter
Token Usage Meter。然后配置 meter:- 开启 Bill usage in credits。
- Select credit:
API Tokens - Meter units per credit:
1。event 中的每个 token 都会扣除一个 credit。 - Free Threshold:
0。Free threshold 仅适用于 meter 以 money 计费的情况。当 meter 以 credits 计费时,每个 unit 都会从余额中扣除。

Toggle 'Bill usage in Credits' on the meter and pick the credit entitlement.
api.tokens_used events 从客户余额中扣除 credits。Configure Credit Issuance for Starter
10000000Import Default Credit Settings:开启,使产品使用 credit entitlement 中设置的 30 天 expiry。Allow Overage:关闭。步骤 1 中的默认设置会保持 overage disabled,因此 Starter 客户的余额会在零时停止。
Configure credit issuance per cycle on the UBB product.
pdt_ 开头。Pro Plan($99/月 — 40M Tokens,启用 Overage)
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:关闭,以便为此产品设置 overage。Allow Overage:开启Price Per Unit:每个 token 0.000005 USD。也就是每 1K tokens 收取 $0.005,或每 1M tokens 收取 $5,高于该计划的有效单 token 费率,因此可以抑制 overage。Overage Behavior:Bill overage at billing。Overage 会在下一张 invoice 上收费,随后余额重置。保存产品并复制其 ID。步骤 4:创建 Token Top-Up Pack
Top-up pack 是一次性购买,可向现有客户的余额中增加 5,000,000 tokens。
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 天 expiry。
- 将 Credit Expiry 设置为 Custom,并输入
365天。 - 保存产品。
步骤 5:构建后端
构建 Express server。它会创建 subscription 和 top-up checkouts,调用 OpenAI 并对 tokens 计费,读取余额,并接收 credit webhook events。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 model,适合高吞吐量请求。package.json tab 会显示完整的 dependency list:How Deductions Happen
- 你的 handler 调用 OpenAI 并读取
usage.total_tokens,例如 1532。 - 你使用
event_name: api.tokens_used和metadata: { tokens: 1532 }ingest 一个 usage event。 Token Usage Meter按 customer 聚合 events。background worker 每分钟处理新 events。- 由于 meter 通过 Bill usage in credits 对
API Tokenscredit 进行 billing,Dodo Payments 会扣除 1532 credits,从客户最先过期的 grant 开始(FIFO)。 - 如果启用了 overage 且 balance 用尽,deficit 会被记录,并在下一张 invoice 中 billing。
步骤 6:添加 Demo Frontend
创建public/index.html,以便在 browser 中测试每个 flow。该页面会将 customer ID 保存到 localStorage,因此 subscribe、generate 和 top-up 会共享同一个 identity,就像已登录的 app 一样:
步骤 7:连接 Webhook
Webhooks 让你的 server 能够响应 balance changes,例如向 balance 较低的 customer 发送 email。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,使用你自己的 tunnel host。 - 至少选择以下 events:
credit.addedcredit.deductedcredit.overage_charged
- 点击 Create endpoint,然后从 endpoint 的 Overview tab 复制 signing secret。
- 将其粘贴到
.env中,作为DODO_PAYMENTS_WEBHOOK_KEY,然后重启npm run dev。
步骤 8:测试完整 Flow
Subscribe a Test Customer
- 运行
npm run dev。 - 打开
http://localhost:3000。 - 选择 Pro,输入测试 email address 和 name,然后点击 Get Checkout Link。使用 test card details 完成 checkout。
- 在 dashboard 中前往 Customers,打开最新的 customer,复制其 ID,该 ID 以
cus_开头。 - 将 ID 粘贴到 demo 中的 Logged-in customer ID 字段,然后点击 Save。
Generate an AI Response
total_tokens,ingest 一个 usage event,然后返回 response。Test the Top-Up Flow
credit.added event。故障排除
Credits not deducting after usage events
Credits not deducting after usage events
- meter 的 event name 与你发送的
event_name不匹配。api.tokens_used区分大小写。 - meter 未关联到 product 上的
API Tokenscredit。打开 product 的 meter configuration,确认 Bill usage in credits 已启用。 metadata.tokenskey 与 meter 的 Over Property 不匹配。- customer 的 grant 已过期。检查 customer 的 credit history。
- 在 Products → Meters 中打开 meter,确认 product attachment 显示了关联的 credit name。
- 打开 meter 的 Events tab。Ingested events 会显示在其中,即使尚未发生 deduction。
- 在 Customers 中打开 customer,然后选择 Credits tab。Ledger entries 会在一到两分钟内显示。
Balance always shows 0 or 'customer not found'
Balance always shows 0 or 'customer not found'
- customer 尚未完成 checkout。只有 payment 成功后才会发放 credits。
- 你使用错误的
customer_id进行 query。请使用 dashboard 中以cus_开头的 ID,而不是自己 database 中的 ID。 .env中的CREDIT_ENTITLEMENT_ID与 product 关联的 credit 不匹配。
Overage not working for Pro plan customers
Overage not working for Pro plan customers
- Pro product 的 credit attachment 未启用 overage。credit 上的设置仅作为 default。
- customer 使用的是 Starter,而不是 Pro。
- Overage Limit 设置为 0。
0.000005(每百万 tokens 为 $5)。检查前导零:该字段接受的是每个 token 的 price,而不是每 1K tokens 的 price。Webhook verification failed in logs
Webhook verification failed in logs
- Body parsing 顺序错误:
express.json()在/webhooks/dodo上运行,早于express.raw()。SDK 需要 request 的 raw bytes,而不是 parsed JSON。 DODO_PAYMENTS_WEBHOOK_KEY保存了错误的 signing secret。- reverse proxy 重写了 request headers。
server.ts 中,app.use('/webhooks/dodo', express.raw(...)) line 位于 app.use(express.json()) 之前。需要帮助?
恭喜!你已为 NeuralAPI 构建基于 Credit 的 Billing
NeuralAPI 现在可以从 checkout 到 deduction 全程使用 credits 进行 billing:Token Credit Entitlement
API Tokens credit,有效期为 30 天,由两个 plans 和 top-up pack 共享。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)会通过 handler 路由,该 handler 使用 SDK 的 Standard Webhooks helper 验证 signatures。- 为
/credits/:customerId和/api/generate添加 authentication。 按当前写法,任何人都可以使用任意 customer ID 调用它们。请对 users 进行 authentication,并在 server 上查询其 customer ID。 - 使用稳定的
event_idvalues。 示例使用Date.now()加上随机字符串。在 production 中,请使用 request ID,使 retries 具备幂等性:Dodo Payments 会忽略其已 ingest 过的event_id所对应的 event。 - 保存 customer-to-user mapping。 在首次 checkout 后将
customer_id保存到 database,这样 users 就不必手动粘贴它。 - 决定 subscription 结束时的处理方式。 Plan credits 会留在 customer 的 ledger 中,直到发放 30 天后过期;top-up credits 的有效期为 365 天。本教程的
/api/generate只检查 balance,不检查 subscription status,因此已取消的 customer 仍可使用剩余 tokens。这是对 customer 更友好的 default。如需更严格的 access 控制,可以:(a) 监听subscription.cancelledwebhook,并根据 subscription status 控制/api/generate;或 (b) 在取消时,通过 ledger API debit 未使用的 plan credits。Debits 会从最先过期的 grant 中扣除,因此 30 天的 plan credits 会先于 365 天的 top-up credits 被扣除。 - 监控 Usage Billing dashboard,及早发现 metering anomalies。