I denna handledning bygger du NeuralAPI — en nivåindelad AI-plattform där varje prenumerationsplan kommer med en månatlig tokenkreditkvot, kunder kan köpa toppningspaket när de har lågt saldo, och din backend drar automatiskt av krediter eftersom begäran behandlas av OpenAI.Documentation Index
Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
Use this file to discover all available pages before exploring further.
Denna handledning använder Node.js/Express + OpenAI SDK. Dodo Payments-koncept (krediter, mätare, webhooks) gäller för alla ramverk eller AI-leverantörer — anpassa fritt.
- Skapa ett anpassat kreditberättigande (tokens) och en mätare som automatiskt drar ifrån det
- Fästa krediter på prenumerationsplaner (med och utan överspill) och en engångs topprodukt
- Ansluta en riktig OpenAI-kompletterande slutpunkt som fakturerar tokens genom Dodo Payments
- Fråga en kunds aktuella kreditsaldo via SDK
- Verifiera webhook-signaturer och dirigera Dodo Payments kredithändelser
Vad Vi Bygger
Här är prismodellen för NeuralAPI:| Produkt | Pris | Tokens | Överspill |
|---|---|---|---|
| Startplan | $29/månad | 10,000,000 tokens/cykel | Blockerat vid noll |
| Pro Plan | $99/månad | 40,000,000 tokens/cykel | $0,005 per 1K tokens |
| Token Top-Up Pack | $19 engångsavgift | +5,000,000 tokens | — |
Innan du börjar, se till att du har:
- Ett Dodo Payments-konto (testläge är okej)
- En OpenAI API-nyckel
- Node.js 18+
- Grundläggande kunskaper i TypeScript/Node.js
Steg 1: Skapa Ditt Token Krediteringsberättigande
Först skapar du kreditberättigandet som både prenumerationsplanerna och toppningspaketet delar. Tänk på detta som att definiera den “token”-enhet din plattform använder.
Navigate to Credits
- Logga in på din Dodo Payments-instrumentpanel
- Klicka på Produkter i den vänstra sidopanelen
- Välj fliken Krediter
- Klicka på Skapa Kredit
Configure the credit unit
Fyll i de grundläggande detaljerna för din tokenkredit:Kreditnamn:
API TokensKredittype: Välj Anpassad EnhetEnhetsnamn: tokenPrecision: 0 (tokens är alltid hela nummer)Kredits Utgång: 30 days (krediter återställs varje faktureringscykel)Skip overage at the credit level
Lämna överspill avaktiverad här — du kommer att konfigurera det per plan när du fäster krediten på produkter. Detta gör att startplanen blockerar användning vid noll medan Pro-planen tillåter överspill.
Click Skapa Kredit. När den är sparad, öppna krediten och kopiera dess ID — det ser ut som
cent_xxxxxxxxxxxx.Your
API Tokens kreditberättigande är klart. Nästa steg är att skapa en mätare så att användningshändelser kan driva avdrag automatiskt.En mätare aggregerar inkommande användningshändelser och omvandlar dem till kreditavdrag. Du behöver detta innan du skapar planprodukterna, eftersom du kommer att fästa det under produktens skapande i Steg 3.
Event-namn är skiftlägeskänsliga.
api.tokens_used ≠ Api.Tokens.Used — välj ett och håll dig till det.Båda planerna behöver vara Användningsbaserade faktureringsprodukter, inte vanliga prenumerationer — mätare kan endast fästas vid UBB-produkter, och du behöver mätaren för att automatiskt dra av krediter när kunder anropar ditt API. UBB-produkter stöder fortfarande en återkommande grundavgift (den
$29 / $99); användning ovanpå det faktureras i krediter.Beskrivning:
10 million API tokens per month. Perfect for individual developers and small projects.Fast Pris:
29.00 (den återkommande grundavgiften – debiteras månatligen även innan någon användning)API Tokens1 — varje token i händelsen kartläggs till 1 kredit som dras av0 — kreditallokeringen i sig är kundens “fria nivå”; vi behöver inte ett extra gratisbandDetta är kopplingen som gör att inkommande
api.tokens_used händelser faktiskt drar av från kundens saldo.Fortsätt på produkten, scrolla till kreditkonfigurationsavsnittet som visas när en kreditfakturerad mätare är fäst:
Importera Standardkreditinställningar: Aktiverat — använd 30 dagars förfallodatum från kreditberättigandet
Startplan: $29/månad grundavgift, 10M tokens/cykel, blockerat vid noll, automatisk avdrag via mätare.
Identisk med Start: lägg till
Token Usage Meter, växla Fakturera användning i krediter på, välj API Tokens, Mätare enheter per kredit 1, Fri Tröskel 0.Importera Standardkreditinställningar: Inaktiverad — vi behöver anpassa överspillinställningar per produkt
Pris Per Enhet:
0.000005 USD per token (dvs. 5 per 1M tokens — över planens effektiva per-token-pris för att avskräcka överspill)Överspill Beteende:
Bill overage at billing — överspill faktureras på nästa faktura, sedan återställs saldotAPI Tokens5000000365 daysVarför längre utgång på toppningar? Prenumerationskrediter återställs var 30 dag eftersom det är cykeln. Toppningar är förbetalda köp — kunden betalade $19 i förskott och förväntar sig rimligen att de tokens ska hålla längre än en månad. 365 dagar matchar hur riktiga förbetalda krediter fungerar på OpenAI, AWS och Anthropic, medan de ändå begränsar ditt ansvar så att kunderna inte kan lagra obegränsat.
Nu ska vi bygga Express-servern som hanterar prenumerationsutcheckning, topputcheckning, verkliga OpenAI-kompletteringar med tokenfakturering, balansfrågor och kredit-webhook-händelser.
Backend klar: prenumerationsutcheckning, topputcheckning, OpenAI-komplettering med mätt tokenfakturering, balansfråga och en verifierad webhook-hanterare.
Du kanske har märkt att det inte finns någon uttrycklig “dra av N krediter”-anrop. Det är avsiktligt:
usage.total_tokens (t.ex. 1532).event_name: api.tokens_used, metadata: { tokens: 1532 }.Token Usage Meter aggregerar händelser per kund.API Tokens kredit med Fakturera användning i Krediter, drar Dodo Payments av 1532 krediter från kundens äldsta obegränsade beviljning (FIFO).Skapa
public/index.html för att testa alla flöden i din webbläsare. Vi sparar kund-ID:t till localStorage så att prenumerera → generera → topp alla delar samma identitet, vilket mimar en inloggad app:Webhooks låter din server reagera på saldoförändringar — du använder dem för att skicka “lågt saldo”-mail innan kunderna når noll.
Webhooks behöver en offentlig URL. För lokal utveckling, använd ngrok eller någon tunnel:
https://your-tunnel.ngrok-free.app/webhooks/dodocredit.addedcredit.deductedcredit.overage_charged
.env som DODO_PAYMENTS_WEBHOOK_KEY, starta sedan om npm run devSDK:n
dodo.webhooks.unwrap() validerar webhook-id, webhook-timestamp och webhook-signature headers med din signeringshemlighet. Du behöver inte rolla din egen HMAC-verifiering - och du borde inte, för Dodo Payments använder Standard Webhooks, som signerar id.timestamp.body snarare än bara kroppen.npm run devhttp://localhost:3000cus_... IDSkriv en prompt och klicka på Generera. Servern anropar OpenAI, får tillbaka den faktiska
total_tokens, registrerar en användningshändelse och returnerar svaret.Användningshändelser behandlas av en bakgrundsarbetare varje ~minut. Balansen kommer inte att ticka ner direkt — vänta 30–90 sekunder och klicka Uppdatera Saldo igen. Dra inte slutsatsen att det är trasigt om första uppdateringen inte visar någon rörelse.
Klicka på Köp 5M Tokens — $19 och slutför utcheckning. Efter att betalningen lyckas, uppdatera saldot — det bör hoppa med 5,000,000 tokens. Din serverlogg bör visa en
credit.added händelse.event_name du skickar (api.tokens_used är skiftlägeskänsligt)API Tokens kredit på produkten — gå till produktens mätarkonfiguration och bekräfta Fakturera användning i Krediter är påmetadata.tokens nyckel matchar inte mätarens “Över Egenskap”-fältcustomer_id (använd cus_... ID från instrumentpanelen, inte din egen databass ID)CREDIT_ENTITLEMENT_ID i .env matchar inte krediten kopplad till produktenVad man ska kontrollera:
Öppna Kunder → [Kund] → Krediter. Om inga krediter visas där, kopplades inte produktberättigandet eller betalningen slutfördes inte.
Vad man ska kontrollera:
Redigera Pro → Berättiganden → Krediter → bekräfta Tillåt Överspill är på och Pris Per Enhet är
0.000005 (= $5 per miljoner tokens; dubbelkontrollera de ledande nollorna — fältet tar per-tokenpriset, inte per-1K).express.json() tillämpades på /webhooks/dodo före express.raw() — SDK:n behöver råbytes av förfrågan, inte analyserad JSONDODO_PAYMENTS_WEBHOOK_KEYVad man ska kontrollera:
Bekräfta att raden
app.use('/webhooks/dodo', express.raw(...)) kommer före app.use(express.json()) i server.ts.En återanvändbar
API Tokens kredit med 30 dagars förfallodatum, delad över alla planer och toppningspaketStart (10M, hård gräns) och Pro (40M + överspill) konfigureras per produkt utan duplicering av krediten
Riktiga OpenAI token-konton registrerade som händelser; mätaren drar av krediter FIFO utan manuell spårning
Kreditkontohändelser (
credit.added, credit.deducted, credit.overage_charged) dirigerad genom en signaturverifierad hanterare med hjälp av SDK:s Standard Webhooks-hjälpare/credits/:customerId och /api/generate — för närvarande kan vem som helst slå dessa med valfritt kund-ID. Autentisera användare och slå upp deras kund-ID server-side.event_ids — exemplet använder Date.now() + random. I produktion, använd ditt förfrågan-ID så att upprepningar är idempotenta (Dodo Payments avduplikerar genom event_id).customer_id i din DB efter första utcheckningen så du behöver inte ett manuellt klivste./api/generate kontrollerar endast saldot, inte prenumerationsstatusen. Så en annullerad kund kan fortfarande använda sina kvarvarande tokens. Det är den konsumentvänliga standardinställningen. Om du vill ha strängare åtkomstkontroll, antingen (a) lyssna på subscription.cancelled webhook och gate /api/generate på prenumerationsstatus, eller (b) ring Dodos redovisnings-API för att debitera oanvända plankrediter vid avbokning medan toppkrediter lämnas intakta.Fullständig CBB-dokumentation: rullning, överspill-lägen, redovisningshantering, alla API-slutpunkter.
Troubleshooting
Credits not deducting after usage events
Credits not deducting after usage events
Possible causes:
- The meter’s event name doesn’t match the
event_nameyou’re sending (api.tokens_usedis case-sensitive) - The meter isn’t linked to the
API Tokenscredit on the product — go to the product’s meter configuration and confirm Bill usage in Credits is on - The
metadata.tokenskey doesn’t match the meter’s “Over Property” field - The customer’s grant has expired (check the customer’s credit history)
- Products → Meters: open the meter and confirm it shows the linked credit name on the product attachment
- The Events tab on the meter — ingested events should appear there even before deduction
- Customers → [Customer] → Credits: ledger entries should appear within a minute or two
Balance always shows 0 or 'customer not found'
Balance always shows 0 or 'customer not found'
Possible causes:
- The customer hasn’t completed checkout yet — credits are only issued after a successful payment
- You’re querying with the wrong
customer_id(use thecus_...ID from the dashboard, not your own DB ID) - The
CREDIT_ENTITLEMENT_IDin.envdoesn’t match the credit attached to the product
Overage not working for Pro plan customers
Overage not working for Pro plan customers
Possible causes:
- Overage wasn’t enabled on the Pro product’s credit attachment (the credit-level setting is just a default)
- The customer is actually on Starter, not Pro
- Overage limit was set to 0
0.000005 (= $5 per million tokens; double-check the leading zeros — the field takes per-token price, not per-1K).`Webhook verification failed` in logs
`Webhook verification failed` in logs
Possible causes:
- Body parsing order:
express.json()was applied to/webhooks/dodobeforeexpress.raw()— the SDK needs the raw bytes of the request, not parsed JSON - Wrong signing secret in
DODO_PAYMENTS_WEBHOOK_KEY - Reverse proxy is rewriting headers
app.use('/webhooks/dodo', express.raw(...)) line comes before app.use(express.json()) in server.ts.Need help?
Congratulations! You’ve Built Credit-Based Billing for NeuralAPI
Your platform now has a complete, production-ready credit billing system:Token Credit Entitlement
A reusable
API Tokens credit with 30-day expiry, shared across all plans and the top-up packTiered Plans, One Credit
Starter (10M, hard limit) and Pro (40M + overage) configured per-product without duplicating the credit
One-Time Top-Up Pack
Customers add 5M tokens for $19 without changing their subscription
Auto-Deduction via Meter
Real OpenAI token counts ingested as events; the meter deducts credits FIFO with no manual tracking
Live Balance API
Real-time balance via the SDK to gate access, display usage, or warn customers in-app
Verified Webhook Pipeline
Credit ledger events (
credit.added, credit.deducted, credit.overage_charged) routed through a signature-verified handler using the SDK’s Standard Webhooks helperGoing to production? Tighten these:
- Auth on
/credits/:customerIdand/api/generate— currently anyone can hit these with any customer ID. Authenticate users and look up their customer ID server-side. - Stable
event_ids — the example usesDate.now() + random. In production, use your request ID so retries are idempotent (Dodo Payments deduplicates byevent_id). - Persist the customer↔user mapping — store
customer_idin your DB after the first checkout so you don’t need a manual paste step. - Decide what happens when a subscription ends. Plan credits remain in the customer’s ledger until their natural expiry (30 days from issuance) and top-up credits stay valid for 365 days — but the cookbook’s
/api/generateonly checks balance, not subscription status. So a cancelled customer can still consume their remaining tokens. That’s the consumer-friendly default. If you want stricter access control, either (a) listen to thesubscription.cancelledwebhook and gate/api/generateon subscription status, or (b) call Dodo’s ledger API to debit unused plan credits on cancel while leaving top-up credits intact. - Monitor the Usage Billing dashboard to catch metering anomalies early.
Credit-Based Billing Reference
Full CBB documentation: rollover, overage modes, ledger management, all API endpoints.
Credit Webhook Events
Payload schemas for every credit event your server might receive.