Skip to main content
如果希望由 coding agent 编写集成代码,请安装 Dodo Agent Plugin。它会将 Dodo Payments skills 和 MCP servers 添加到 Claude Code、Codex CLI、Cursor、VS Code / GitHub Copilot、Kiro 和 OpenCode。
你将构建 NeuralAPI,这是一个分层 AI API,每个订阅计划都包含每月 token credits 配额。余额不足的客户可以购买充值包,而你的后端会报告每个 OpenAI 请求使用的 tokens,以便 Dodo Payments 从客户余额中扣除相应 credits。
本教程使用 Node.js、Express 和 OpenAI SDK。无论使用哪种 framework 或 AI provider,Dodo Payments 的 concepts(credits、meters 和 webhooks)都以相同方式工作。
完成后,你将了解如何:
  • 为 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 单位。
显示已创建 credit entitlements 的 Credits 列表页面

The Credits tab under Products shows all your credit entitlements.

1

Navigate to Credits

  1. 登录 Dodo Payments dashboard。
  2. 在侧边栏中点击 Products。
  3. 选择 Credits 标签页。
  4. 点击 Create Credit。
2

Configure the Credit Unit

输入以下值:Credit Name:API TokensCredit Type:Custom UnitUnit Name:tokenDefine Precision:0。Token 数量为整数。Credit Expiry:30 days。Credits 会在发放 30 天后过期,这与每月计费周期一致。
创建 credit 后无法更改 Precision。对于 token 数量,请使用 0。
3

Skip Overage at the Credit Level

将 credit 上的 overage 保持为 disabled。将 credit 附加到每个产品时,可以按计划配置此设置,因此 Starter plan 可以在余额为零时阻止使用,而 Pro plan 可以允许 overage。
Credit 上的 overage settings 是默认值。每个产品 attachment 都可以覆盖这些设置,步骤 3 会为 Pro plan 执行此操作。
4

Save and Copy the Credit ID

点击 Create Credit。打开保存的 credit,并复制其 ID;该 ID 以 cde_ 开头。
API Tokens credit entitlement 已准备就绪。接下来创建 meter,使 usage events 能够扣除 credits。

步骤 2:创建 Token Usage Meter

Meter 会聚合传入的 usage events。当你将它链接到 credit 后,聚合的 usage 会从客户的 credit balance 中扣除。请在创建计划产品之前创建 meter,因为你需要在步骤 3 创建产品时附加它。
1

Open the Meters Section

  1. 在 dashboard 侧边栏中前往 Products → Meters。
  2. 点击 Create Meter。
2

Configure the Meter

输入以下值:Meter Name:Token Usage MeterEvent Name:api.tokens_used。它必须与应用发送的 event_name 匹配。Aggregation Type:Sum,用于累加每个 event 中的 token count。Over Property:tokens,即要汇总其值的 metadata key。Measurement Unit:tokens
Event names 区分大小写:api.tokens_used 和 Api.Tokens.Used 是不同的 events。创建 meter 后无法编辑,因此确认前请检查每个值。
创建 meter。将它附加到产品时,你会按名称选择它。
Meter 已创建。接下来将它链接到每个计划产品上的 credit。

步骤 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 configuration

Usage Based Billing pricing type with meter configuration.

Starter Plan($29/月 — 10M Tokens,不允许 Overage)

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。这是 recurring base fee,即使尚未产生任何 usage,也会每月收取。Repeat payment every:1 monthCurrency:USD
2

Attach the Meter

在 Select meter 部分点击 +,添加 Token Usage Meter。然后配置 meter:
  1. 开启 Bill usage in credits。
  2. Select credit:API Tokens
  3. Meter units per credit:1。event 中的每个 token 都会扣除一个 credit。
  4. Free Threshold:0。Free threshold 仅适用于 meter 以 money 计费的情况。当 meter 以 credits 计费时,每个 unit 都会从余额中扣除。
已启用 Bill usage in Credits 且选中 API Tokens 的 meter

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

正是这个链接使传入的 api.tokens_used events 从客户余额中扣除 credits。
3

Configure Credit Issuance for Starter

附加 credit-billed meter 后,产品会显示 credit configuration 部分。输入:Credits issued per billing cycle:10000000Import Default Credit Settings:开启,使产品使用 credit entitlement 中设置的 30 天 expiry。Allow Overage:关闭。步骤 1 中的默认设置会保持 overage disabled,因此 Starter 客户的余额会在零时停止。
包含每周期数量和 overage settings 的 credit configuration 表单

Configure credit issuance per cycle on the UBB product.

保存产品并复制其 ID;该 ID 以 pdt_ 开头。
Starter Plan:$29/月 base fee,每周期 10M tokens,余额为零时停止,并通过 meter 扣除。

Pro Plan($99/月 — 40M Tokens,启用 Overage)

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 一样配置 meter:添加 Token Usage Meter,开启 Bill usage in credits,选择 API Tokens,并将 Meter units per credit 设置为 1,将 Free Threshold 设置为 0。
3

Configure Credit Issuance with Overage

配置 credit issuance,这次启用 overage:Credits issued per billing cycle: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。
Pro Plan:$99/月 base fee,每周期 40M tokens,overage 为每 1K tokens 收取 $0.005,并通过 meter 扣除。

步骤 4:创建 Token Top-Up Pack

Top-up pack 是一次性购买,可向现有客户的余额中增加 5,000,000 tokens。
选择 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 天 expiry。
  5. 将 Credit Expiry 设置为 Custom,并输入 365 天。
  6. 保存产品。
复制产品 ID。
为什么充值的有效期更长?订阅 credits 会在 30 天后过期,因为这就是计费周期。充值属于预付购买:客户预先支付了 $19,并希望 tokens 的有效期超过一个月。365 天的有效期符合 OpenAI 和 Anthropic 对预付 API credits 的处理方式:购买的 credits 会在购买一年后过期,同时也能限制你的潜在责任,避免客户无限期囤积 credits。
Top-Up Pack 已配置完成。购买它会授予 5,000,000 tokens,有效期为 365 天。

步骤 5:构建后端

构建 Express server。它会创建 subscription 和 top-up checkouts,调用 OpenAI 并对 tokens 计费,读取余额,并接收 credit webhook events。
1

Set Up Your Project

创建一个 tsconfig.json:
tsconfig.json
更新 package.json scripts:
package.json
2

Set Up Environment Variables

使用来自 Developer → API Keys 的 test mode API key 以及前面步骤中的 IDs,创建 .env:
.env
绝不要将 .env 提交到 version control。在首次 commit 前,将它添加到 .gitignore。
在注册 webhook endpoint 后,于步骤 7 中填写 DODO_PAYMENTS_WEBHOOK_KEY。
3

Implement the Server

创建 src/server.ts。completion endpoint 会调用 OpenAI 的 gpt-6-luna model,适合高吞吐量请求。package.json tab 会显示完整的 dependency list:
backend 已完成:subscription checkout、top-up checkout、带 metered token billing 的 OpenAI completion、balance read,以及经过验证的 webhook handler。
@dodopayments/ingestion-blueprints 提供 trackers,帮你完成 usageEvents.ingest call,包括 LLM Blueprint、API gateway、object storage、streams 和 time-range usage。
4

How Deductions Happen

server 从不调用“deduct N credits” endpoint。由 meter 执行 deduction:
  1. 你的 handler 调用 OpenAI 并读取 usage.total_tokens,例如 1532。
  2. 你使用 event_name: api.tokens_used 和 metadata: { tokens: 1532 } ingest 一个 usage event。
  3. Token Usage Meter 按 customer 聚合 events。background worker 每分钟处理新 events。
  4. 由于 meter 通过 Bill usage in credits 对 API Tokens credit 进行 billing,Dodo Payments 会扣除 1532 credits,从客户最先过期的 grant 开始(FIFO)。
  5. 如果启用了 overage 且 balance 用尽,deficit 会被记录,并在下一张 invoice 中 billing。
你的代码只负责 ingest events。

步骤 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。
1

Expose Your Local Server

Webhooks 需要 public URL。在 local development 中,可以使用 ngrok 或其他 tunnel:
复制 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,使用你自己的 tunnel host。
  3. 至少选择以下 events:
    • credit.added
    • credit.deducted
    • credit.overage_charged
  4. 点击 Create endpoint,然后从 endpoint 的 Overview tab 复制 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,它签名的是 id.timestamp.body,而不仅仅是 body。

步骤 8:测试完整 Flow

1

Subscribe a Test Customer

  1. 运行 npm run dev。
  2. 打开 http://localhost:3000。
  3. 选择 Pro,输入测试 email address 和 name,然后点击 Get Checkout Link。使用 test card details 完成 checkout。
  4. 在 dashboard 中前往 Customers,打开最新的 customer,复制其 ID,该 ID 以 cus_ 开头。
  5. 将 ID 粘贴到 demo 中的 Logged-in customer ID 字段,然后点击 Save。
该 customer 拥有 40,000,000 tokens。点击 Refresh Balance 进行确认。
2

Generate an AI Response

输入 prompt 并点击 Generate。server 会调用 OpenAI,读取实际的 total_tokens,ingest 一个 usage event,然后返回 response。
background worker 每分钟处理 usage events,因此 balance 不会立即减少。等待一到两分钟,然后再次点击 Refresh Balance。第一次 refresh 时 balance 未发生变化,并不表示 metering 失败。
3

Test the Top-Up Flow

点击 Buy 5M Tokens — $19 并完成 checkout。payment 成功后,刷新 balance:balance 会增加 5,000,000 tokens,且 server log 会显示一个 credit.added event。

故障排除

可能原因:
  • meter 的 event name 与你发送的 event_name 不匹配。api.tokens_used 区分大小写。
  • meter 未关联到 product 上的 API Tokens credit。打开 product 的 meter configuration,确认 Bill usage in credits 已启用。
  • metadata.tokens key 与 meter 的 Over Property 不匹配。
  • customer 的 grant 已过期。检查 customer 的 credit history。
检查内容:
  1. 在 Products → Meters 中打开 meter,确认 product attachment 显示了关联的 credit name。
  2. 打开 meter 的 Events tab。Ingested events 会显示在其中,即使尚未发生 deduction。
  3. 在 Customers 中打开 customer,然后选择 Credits tab。Ledger entries 会在一到两分钟内显示。
可能原因:
  • customer 尚未完成 checkout。只有 payment 成功后才会发放 credits。
  • 你使用错误的 customer_id 进行 query。请使用 dashboard 中以 cus_ 开头的 ID,而不是自己 database 中的 ID。
  • .env 中的 CREDIT_ENTITLEMENT_ID 与 product 关联的 credit 不匹配。
检查内容: 在 Customers 中打开 customer,然后选择 Credits tab。如果没有显示 credits,说明该 credit 未关联到 product,或 payment 未完成。
可能原因:
  • Pro product 的 credit attachment 未启用 overage。credit 上的设置仅作为 default。
  • customer 使用的是 Starter,而不是 Pro。
  • Overage Limit 设置为 0。
检查内容: 编辑 Pro product,在 Entitlements 中打开 credit,确认 Allow Overage 已启用,并且 Price Per Unit 为 0.000005(每百万 tokens 为 $5)。检查前导零:该字段接受的是每个 token 的 price,而不是每 1K tokens 的 price。
可能原因:
  • 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

Starter(10M tokens,hard limit)和 Pro(40M tokens 加 overage),按 product 配置,无需重复创建 credit。

One-Time Top-Up Pack

Customers 可以支付 $19 增加 5M tokens,而无需更改 subscription。

Deduction Through a Meter

实际的 OpenAI token counts 会作为 events ingest,meter 会按 FIFO 扣除 credits,无需手动 tracking。

Live Balance API

通过 SDK 读取当前 balance,以便在 app 中控制 access、显示 usage 或向 customers 发出 warning。

Verified Webhook Pipeline

Credit ledger events(credit.added、credit.deducted、credit.overage_charged)会通过 handler 路由,该 handler 使用 SDK 的 Standard Webhooks helper 验证 signatures。
准备投入 production? 请加强以下设置:
  • 为 /credits/:customerId 和 /api/generate 添加 authentication。 按当前写法,任何人都可以使用任意 customer ID 调用它们。请对 users 进行 authentication,并在 server 上查询其 customer ID。
  • 使用稳定的 event_id values。 示例使用 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.cancelled webhook,并根据 subscription status 控制 /api/generate;或 (b) 在取消时,通过 ledger API debit 未使用的 plan credits。Debits 会从最先过期的 grant 中扣除,因此 30 天的 plan credits 会先于 365 天的 top-up credits 被扣除。
  • 监控 Usage Billing dashboard,及早发现 metering anomalies。

Credit-Based Billing Reference

Rollover、overage modes、ledger management 以及每个 credit API endpoint。

Credit Webhook Events

你的 server 可以接收的每个 credit event 的 payload schemas。
最后修改于 2026年9月26日