Skip to main content
Damit dein Coding-Agent die Integration erstellt, installiere das Dodo Agent Plugin. Es fügt Claude Code, Codex CLI, Cursor, VS Code / GitHub Copilot, Kiro und OpenCode die Dodo Payments Skills und MCP-Server hinzu.
Du erstellst NeuralAPI, eine abgestufte AI-API, bei der jeder Abonnementplan ein monatliches Kontingent an Token-Credits enthält. Kunden, deren Kontingent knapp wird, kaufen ein Aufladepaket. Dein Backend meldet die von jeder OpenAI-Anfrage verwendeten Tokens, damit Dodo Payments sie vom Guthaben des Kunden abziehen kann.
Dieses Tutorial verwendet Node.js, Express und das OpenAI SDK. Die Dodo Payments-Konzepte (Credits, Meter und Webhooks) funktionieren mit jedem Framework und jedem AI-Anbieter gleich.
Am Ende weißt du, wie du Folgendes machst:
  • Eine benutzerdefinierte Credit-Berechtigung für Tokens und einen Meter erstellen, der davon abzieht.
  • Credits mit und ohne Mehrverbrauch an Abonnementpläne sowie an ein einmaliges Aufladeprodukt anhängen.
  • OpenAI über einen Endpunkt aufrufen, der Tokens über Dodo Payments abrechnet.
  • Das aktuelle Credit-Guthaben eines Kunden mit dem SDK auslesen.
  • Webhook-Signaturen überprüfen und Dodo Payments-Credit-Ereignisse weiterleiten.

Was wir erstellen

NeuralAPI verkauft drei Produkte: Bevor du beginnst, benötigst du:
  • Ein Dodo Payments-Konto. Führe alles im Testmodus aus.
  • Einen OpenAI API-Schlüssel.
  • Node.js 22 oder höher sowie Kenntnisse in TypeScript und Node.js.

Schritt 1: Token-Credit-Berechtigung erstellen

Erstelle die Credit-Berechtigung, die von beiden Plänen und dem Aufladepaket gemeinsam verwendet wird. Sie definiert die Token-Einheit, die NeuralAPI verkauft.
Seite mit der Liste der Credits und erstellten Credit-Berechtigungen

The Credits tab under Products shows all your credit entitlements.

1

Navigate to Credits

  1. Melde dich im Dodo Payments-Dashboard an.
  2. Klicke in der Seitenleiste auf Products.
  3. Wähle den Tab Credits aus.
  4. Klicke auf Create Credit.
2

Configure the Credit Unit

Gib diese Werte ein:Credit Name: API TokensCredit Type: Custom UnitUnit Name: tokenDefine Precision: 0. Tokenanzahlen sind ganze Zahlen.Credit Expiry: 30 days. Credits laufen 30 Tage nach ihrer Ausstellung ab, passend zum monatlichen Abrechnungszyklus.
Die Genauigkeit kann nach dem Erstellen des Credits nicht mehr geändert werden. Für Tokenanzahlen verwendest du 0.
3

Skip Overage at the Credit Level

Lass den Mehrverbrauch für den Credit deaktiviert. Du konfigurierst ihn pro Plan, wenn du den Credit an jedes Produkt anhängst. Dadurch kann der Starter-Plan die Nutzung bei null blockieren, während der Pro-Plan Mehrverbrauch erlaubt.
Die Mehrverbrauchseinstellungen des Credits sind Standardwerte. Jeder Produktanhang kann sie überschreiben, wie es Schritt 3 für den Pro-Plan macht.
4

Save and Copy the Credit ID

Klicke auf Create Credit. Öffne den gespeicherten Credit und kopiere seine ID, die mit cde_ beginnt.
Die Credit-Berechtigung API Tokens ist bereit. Erstelle als Nächstes einen Meter, damit Nutzungsevents Credits abziehen.

Schritt 2: Meter für die Token-Nutzung erstellen

Ein Meter aggregiert eingehende Nutzungsevents. Wenn du ihn mit einem Credit verknüpfst, wird die aggregierte Nutzung vom Credit-Guthaben des Kunden abgezogen. Erstelle den Meter vor den Produktplänen, da du ihn beim Erstellen in Schritt 3 anhängst.
1

Open the Meters Section

  1. Gehe in der Dashboard-Seitenleiste zu Products → Meters.
  2. Klicke auf Create Meter.
2

Configure the Meter

Gib diese Werte ein:Meter Name: Token Usage MeterEvent Name: api.tokens_used. Dies muss mit dem event_name übereinstimmen, das deine App sendet.Aggregation Type: Sum, um die Tokenanzahl jedes Events zu addieren.Over Property: tokens, der Metadatenschlüssel, dessen Wert summiert wird.Measurement Unit: tokens
Eventnamen berücksichtigen Groß- und Kleinschreibung: api.tokens_used und Api.Tokens.Used sind unterschiedliche Events. Du kannst einen Meter nach dem Erstellen nicht bearbeiten. Überprüfe daher jeden Wert, bevor du bestätigst.
Erstelle den Meter. Du wählst ihn beim Anhängen an Produkte anhand seines Namens aus.
Der Meter wurde erstellt. Verknüpfe ihn als Nächstes mit dem Credit jedes Planprodukts.

Schritt 3: Planprodukte erstellen

Erstelle beide Pläne mit dem Preistyp Usage Based Billing, nicht mit einfachem Subscription. Meter werden an Usage Based Billing-Produkte angehängt, und der Meter zieht Credits ab, wenn Kunden deine API aufrufen. Ein Usage Based Billing-Produkt berechnet weiterhin eine wiederkehrende Grundgebühr ($29 oder $99); die darüber hinausgehende Nutzung wird in Credits abgerechnet.
Preiskonfiguration für Usage Based Billing

Usage Based Billing pricing type with meter configuration.

Starter Plan ($29/Monat — 10 Mio. Tokens, kein Mehrverbrauch)

1

Create the Starter Product

  1. Gehe zu Products und klicke auf Add Product.
  2. Wähle unter Pricing Type die Option Usage Based Billing.
  3. Gib diese Werte ein:
Product Name: NeuralAPI StarterDescription: 10 million API tokens per month. Perfect for individual developers and small projects.Price: 29.00. Dies ist die wiederkehrende Grundgebühr, die jeden Monat auch vor jeglicher Nutzung berechnet wird.Repeat payment every: 1 MonatCurrency: USD
2

Attach the Meter

Klicke im Abschnitt Select meter auf + und füge Token Usage Meter hinzu. Konfiguriere den Meter anschließend:
  1. Aktiviere Bill usage in credits.
  2. Select credit: API Tokens
  3. Meter units per credit: 1. Jedes Token in einem Event zieht einen Credit ab.
  4. Free Threshold: 0. Der kostenlose Schwellenwert gilt nur, wenn ein Meter in Geld abrechnet. Bei der Abrechnung in Credits wird jede Einheit vom Guthaben abgezogen.
Meter mit aktivierter Option Bill usage in Credits und ausgewählten API Tokens

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

Diese Verknüpfung bewirkt, dass eingehende api.tokens_used-Events vom Guthaben des Kunden abgezogen werden.
3

Configure Credit Issuance for Starter

Nachdem du einen in Credits abgerechneten Meter angehängt hast, zeigt das Produkt einen Abschnitt für die Credit-Konfiguration. Gib Folgendes ein:Credits issued per billing cycle: 10000000Import Default Credit Settings: aktiviert, damit das Produkt das Ablaufdatum von 30 Tagen aus der Credit-Berechtigung verwendet.Allow Overage: deaktiviert. Der Standardwert aus Schritt 1 lässt den Mehrverbrauch deaktiviert, sodass Starter-Kunden bei null stoppen.
Credit-Konfigurationsformular mit Betrag pro Zyklus und Mehrverbrauchseinstellungen

Configure credit issuance per cycle on the UBB product.

Speichere das Produkt und kopiere seine ID, die mit pdt_ beginnt.
Starter Plan: Grundgebühr von $29/Monat, 10 Mio. Tokens pro Zyklus, bei null blockiert und über den Meter abgezogen.

Pro Plan ($99/Monat — 40 Mio. Tokens, Mehrverbrauch aktiviert)

1

Create the Pro Product

Folge dem Starter-Ablauf mit diesen Werten:Product Name: NeuralAPI ProDescription: 40 million API tokens per month with overage. Built for production applications.Price: 99.00Repeat payment every: 1 MonatCurrency: USD
2

Attach the Meter

Konfiguriere den Meter wie für Starter: Füge Token Usage Meter hinzu, aktiviere Bill usage in credits, wähle API Tokens und setze Meter units per credit auf 1 sowie Free Threshold auf 0.
3

Configure Credit Issuance with Overage

Konfiguriere die Credit-Ausstellung diesmal mit aktiviertem Mehrverbrauch:Credits issued per billing cycle: 40000000Import Default Credit Settings: deaktiviert, damit du den Mehrverbrauch für dieses Produkt festlegen kannst.Allow Overage: aktiviertPrice Per Unit: 0.000005 USD pro Token. Das entspricht $0.005 pro 1K Tokens oder $5 pro 1 Mio. Tokens. Dieser Preis liegt über dem effektiven Preis pro Token des Plans und wirkt Mehrverbrauch entgegen.Overage Behavior: Bill overage at billing. Der Mehrverbrauch wird auf der nächsten Rechnung berechnet; anschließend wird das Guthaben zurückgesetzt.Speichere das Produkt und kopiere seine ID.
Pro Plan: Grundgebühr von $99/Monat, 40 Mio. Tokens pro Zyklus, Mehrverbrauch zu $0.005 pro 1K Tokens und Abzug über den Meter.

Schritt 4: Token Top-Up Pack erstellen

Das Aufladepaket ist ein einmaliger Kauf, der dem Guthaben eines bestehenden Kunden 5.000.000 Tokens hinzufügt.
Produktpreisabschnitt mit ausgewählter Option Single Payment

One-time pricing selected for a credit product.

1

Create a One-Time Product

  1. Gehe zu Products und klicke auf Add Product.
  2. Wähle unter Pricing Type die Option One Time.
  3. Gib diese Werte ein:
Product Name: Token Top-Up PackDescription: Add 5 million tokens to your NeuralAPI balance.Price: 19.00Currency: USD
2

Attach the Token Credit

  1. Klicke im Abschnitt Entitlements neben Credits auf Attach.
  2. Wähle API Tokens aus.
  3. Setze No of credits issued auf 5000000.
  4. Deaktiviere Import Default Credit Settings, um das standardmäßige Ablaufdatum von 30 Tagen zu überschreiben.
  5. Setze Credit Expiry auf Custom und gib 365 Tage ein.
  6. Speichere das Produkt.
Kopiere die Produkt-ID.
Warum eine längere Gültigkeitsdauer für Aufladungen? Abonnementguthaben verfällt nach 30 Tagen, weil das dem Abrechnungszyklus entspricht. Eine Aufladung ist ein vorausbezahlter Kauf: Der Kunde hat 19$ im Voraus bezahlt und erwartet, dass die Tokens länger als einen Monat gültig sind. Eine Gültigkeitsdauer von 365 Tagen entspricht der Funktionsweise vorausbezahlter API-Guthaben bei OpenAI und Anthropic, bei denen gekaufte Guthaben ein Jahr nach dem Kauf verfallen. Gleichzeitig wird deine Haftung begrenzt, sodass Kunden nicht unbegrenzt Guthaben ansammeln können.
Das Token Top-Up Pack ist konfiguriert. Der Kauf gewährt 5.000.000 Tokens, die 365 Tage gültig bleiben.

Schritt 5: Backend erstellen

Erstelle den Express-Server. Er erstellt Checkouts für Abonnements und Aufladungen, ruft OpenAI auf und berechnet die Tokens, liest Guthaben aus und empfängt Credit-Webhook-Ereignisse.
1

Set Up Your Project

Erstelle eine tsconfig.json:
tsconfig.json
Aktualisiere die Skripte von package.json:
package.json
2

Set Up Environment Variables

Erstelle .env mit einem API-Schlüssel für den Testmodus aus Developer → API Keys und den IDs aus den vorherigen Schritten:
.env
Committe .env niemals in die Versionsverwaltung. Füge sie vor deinem ersten Commit zu .gitignore hinzu.
Du trägst DODO_PAYMENTS_WEBHOOK_KEY in Schritt 7 ein, nachdem du den Webhook-Endpunkt registriert hast.
3

Implement the Server

Erstelle src/server.ts. Der Completion-Endpunkt ruft das Modell gpt-6-luna von OpenAI auf, das sich für Anfragen mit hohem Volumen eignet. Der Tab package.json zeigt die vollständige Liste der Abhängigkeiten:
Das Backend ist fertig: Subscription-Checkout, Aufladungs-Checkout, eine OpenAI-Completion mit verbrauchsabhängiger Token-Abrechnung, das Abrufen des Kontostands und ein verifizierter Webhook-Handler.
@dodopayments/ingestion-blueprints stellt Tracker bereit, die den Aufruf von usageEvents.ingest für dich übernehmen, einschließlich der Nutzung von LLM Blueprint, API gateway, object storage, streams und time-range.
4

How Deductions Happen

Der Server ruft niemals einen Endpunkt wie „deduct N credits“ auf. Der Meter führt den Abzug durch:
  1. Dein Handler ruft OpenAI auf und liest usage.total_tokens, zum Beispiel 1532.
  2. Du nimmst ein Nutzungsereignis mit event_name: api.tokens_used und metadata: { tokens: 1532 } auf.
  3. Token Usage Meter aggregiert Ereignisse pro Kunde. Ein Hintergrund-Worker verarbeitet neue Ereignisse jede Minute.
  4. Da der Meter das API Tokens-Guthaben über Bill usage in credits abrechnet, zieht Dodo Payments 1532 Guthaben ab, beginnend mit dem Guthaben des Kunden, das zuerst verfällt (FIFO).
  5. Wenn Overages aktiviert sind und das Guthaben aufgebraucht ist, wird das Defizit erfasst und auf der nächsten Rechnung abgerechnet.
Dein Code nimmt ausschließlich Ereignisse auf.

Schritt 6: Ein Demo-Frontend hinzufügen

Erstelle public/index.html, um jeden Ablauf in deinem Browser zu testen. Die Seite speichert die Kunden-ID in localStorage, sodass Abonnement, Generierung und Aufladung dieselbe Identität verwenden – wie in einer App mit angemeldeten Benutzern:

Schritt 7: Den Webhook einrichten

Webhooks ermöglichen es deinem Server, auf Änderungen des Kontostands zu reagieren, zum Beispiel einem Kunden eine E-Mail zu senden, dessen Guthaben knapp wird.
1

Expose Your Local Server

Webhooks benötigen eine öffentliche URL. Verwende für die lokale Entwicklung ngrok oder einen anderen Tunnel:
Kopiere die HTTPS-Weiterleitungs-URL, die auf ngrok-free.app endet.
2

Register the Webhook in Dodo Payments

  1. Gehe im Dashboard zu Developer → Webhooks und klicke auf Add endpoint.
  2. Gib die URL https://your-tunnel.ngrok-free.app/webhooks/dodo ein und verwende dabei deinen eigenen Tunnel-Host.
  3. Wähle mindestens diese Ereignisse aus:
    • credit.added
    • credit.deducted
    • credit.overage_charged
  4. Klicke auf Create endpoint und kopiere anschließend das Signaturgeheimnis aus dem Tab Overview des Endpunkts.
  5. Füge es als DODO_PAYMENTS_WEBHOOK_KEY in .env ein und starte anschließend npm run dev neu.
dodo.webhooks.unwrap() des SDK prüft mit deinem Signaturgeheimnis die Header webhook-id, webhook-timestamp und webhook-signature und analysiert anschließend die Payload. Schreibe keine eigene HMAC-Prüfung: Dodo Payments verwendet Standard Webhooks, das id.timestamp.body signiert, nicht nur den Body.

Schritt 8: Den vollständigen Ablauf testen

1

Subscribe a Test Customer

  1. Führe npm run dev aus.
  2. Öffne http://localhost:3000.
  3. Wähle Pro, gib eine Test-E-Mail-Adresse und einen Namen ein und klicke auf Get Checkout Link. Schließe den Checkout mit Testkartendaten ab.
  4. Gehe im Dashboard zu Customers, öffne den neuesten Kunden und kopiere dessen ID. Sie beginnt mit cus_.
  5. Füge die ID in das Feld Logged-in customer ID der Demo ein und klicke auf Save.
Der Kunde verfügt über 40.000.000 Tokens. Klicke auf Refresh Balance, um dies zu bestätigen.
2

Generate an AI Response

Gib einen Prompt ein und klicke auf Generate. Der Server ruft OpenAI auf, liest die tatsächliche Anzahl der Tokens total_tokens, nimmt ein Nutzungsereignis auf und gibt die Antwort zurück.
Ein Hintergrund-Worker verarbeitet Nutzungsereignisse jede Minute, daher sinkt der Kontostand nicht sofort. Warte ein bis zwei Minuten und klicke anschließend erneut auf Refresh Balance. Ein unveränderter Kontostand bei der ersten Aktualisierung bedeutet nicht, dass die Abrechnung fehlgeschlagen ist.
3

Test the Top-Up Flow

Klicke auf Buy 5M Tokens — $19 und schließe den Checkout ab. Aktualisiere nach erfolgreicher Zahlung den Kontostand: Er erhöht sich um 5.000.000 Tokens, und das Serverprotokoll zeigt ein Ereignis credit.added.

Fehlerbehebung

Mögliche Ursachen:
  • Der Ereignisname des Meters stimmt nicht mit dem event_name überein, das du sendest. api.tokens_used unterscheidet zwischen Groß- und Kleinschreibung.
  • Der Meter ist nicht mit dem API Tokens-Guthaben des Produkts verknüpft. Öffne die Meter-Konfiguration des Produkts und bestätige, dass Bill usage in credits aktiviert ist.
  • Der Schlüssel metadata.tokens stimmt nicht mit dem Over Property des Meters überein.
  • Das Guthaben des Kunden ist abgelaufen. Prüfe die Guthabenhistorie des Kunden.
Was du prüfen solltest:
  1. Öffne im Bereich Products → Meters den Meter und bestätige, dass der Produktanhang den Namen des verknüpften Guthabens anzeigt.
  2. Öffne den Tab Events des Meters. Aufgenommene Ereignisse erscheinen dort bereits vor einem Abzug.
  3. Öffne den Kunden unter Customers und wähle den Tab Credits aus. Ledger-Einträge erscheinen innerhalb von ein bis zwei Minuten.
Mögliche Ursachen:
  • Der Kunde hat den Checkout nicht abgeschlossen. Guthaben werden erst nach erfolgreicher Zahlung ausgegeben.
  • Du fragst mit der falschen customer_id ab. Verwende die ID aus dem Dashboard, die mit cus_ beginnt, nicht eine ID aus deiner eigenen Datenbank.
  • CREDIT_ENTITLEMENT_ID in .env stimmt nicht mit dem mit dem Produkt verknüpften Guthaben überein.
Was du prüfen solltest: Öffne den Kunden unter Customers und wähle den Tab Credits aus. Wenn keine Guthaben angezeigt werden, wurde das Guthaben nicht mit dem Produkt verknüpft oder die Zahlung wurde nicht abgeschlossen.
Mögliche Ursachen:
  • Overage ist für den Guthabenanhang des Pro-Produkts nicht aktiviert. Die Einstellung des Guthabens dient nur als Standardwert.
  • Der Kunde hat Starter und nicht Pro.
  • Overage Limit ist auf 0 gesetzt.
Was du prüfen solltest: Bearbeite das Pro-Produkt, öffne das Guthaben unter Entitlements und bestätige, dass Allow Overage aktiviert ist und Price Per Unit auf 0.000005 gesetzt ist (5$ pro Million Tokens). Achte auf die führenden Nullen: Das Feld erwartet einen Preis pro Token, nicht pro 1.000 Tokens.
Mögliche Ursachen:
  • Reihenfolge der Body-Analyse: express.json() wurde auf /webhooks/dodo angewendet, bevor express.raw() ausgeführt wurde. Das SDK benötigt die rohen Bytes der Anfrage, kein analysiertes JSON.
  • DODO_PAYMENTS_WEBHOOK_KEY enthält das falsche Signaturgeheimnis.
  • Ein Reverse Proxy schreibt die Request-Header um.
Was du prüfen solltest: Bestätige, dass die Zeile app.use('/webhooks/dodo', express.raw(...)) vor app.use(express.json()) in server.ts steht.

Benötigst du Hilfe?

Glückwunsch! Du hast eine guthabenbasierte Abrechnung für NeuralAPI erstellt

NeuralAPI rechnet jetzt vom Checkout bis zum Abzug in Guthaben ab:

Token Credit Entitlement

Ein wiederverwendbares API Tokens-Guthaben mit einer Gültigkeitsdauer von 30 Tagen, das von beiden Tarifen und dem Aufladungspaket gemeinsam genutzt wird.

Tiered Plans, One Credit

Starter (10 Mio. Tokens, festes Limit) und Pro (40 Mio. Tokens plus Overage), pro Produkt konfiguriert, ohne das Guthaben zu duplizieren.

One-Time Top-Up Pack

Kunden können 5 Mio. Tokens für 19$ hinzufügen, ohne ihr Abonnement zu ändern.

Deduction Through a Meter

Die tatsächlichen OpenAI-Tokenzahlen werden als Ereignisse aufgenommen, und der Meter zieht Guthaben per FIFO ab – ohne manuelle Nachverfolgung.

Live Balance API

Der aktuelle Kontostand, der über das SDK abgerufen wird, um den Zugriff zu steuern, die Nutzung anzuzeigen oder Kunden in deiner App zu warnen.

Verified Webhook Pipeline

Credit-Ledger-Ereignisse (credit.added, credit.deducted, credit.overage_charged), die über einen Handler geleitet werden, der Signaturen mit dem Standard-Webhooks-Helfer des SDK verifiziert.
Geht es in die Produktion? Verschärfe diese Punkte:
  • Füge /credits/:customerId und /api/generate eine Authentifizierung hinzu. In der aktuellen Form kann jeder beliebige Kunden-ID-Werte an sie senden. Authentifiziere Benutzer und ermittle ihre Kunden-ID auf dem Server.
  • Verwende stabile event_id-Werte. Das Beispiel verwendet Date.now() plus eine zufällige Zeichenfolge. Verwende in der Produktion deine Request-ID, damit Wiederholungsversuche idempotent sind: Dodo Payments ignoriert ein Ereignis, dessen event_id bereits aufgenommen wurde.
  • Speichere die Zuordnung zwischen Kunde und Benutzer. Speichere customer_id nach dem ersten Checkout in deiner Datenbank, damit Benutzer sie nicht manuell einfügen müssen.
  • Lege fest, was beim Ende eines Abonnements geschieht. Tarifguthaben verbleiben im Ledger des Kunden, bis sie 30 Tage nach der Ausgabe verfallen, und Aufladungsguthaben bleiben 365 Tage gültig. /api/generate des Tutorials prüft nur den Kontostand, nicht den Abonnementstatus. Daher kann ein gekündigter Kunde seine verbleibenden Tokens weiterhin verwenden. Das ist der kundenfreundliche Standard. Für einen strengeren Zugriff kannst du entweder (a) auf den subscription.cancelled-Webhook hören und /api/generate anhand des Abonnementstatus beschränken oder (b) bei der Kündigung die nicht verwendeten Tarifguthaben über die Ledger API abbuchen. Abbuchungen greifen auf das Guthaben zurück, das zuerst verfällt, daher werden die 30-Tage-Tarifguthaben vor den 365-Tage-Aufladungsguthaben verwendet.
  • Überwache das Usage Billing-Dashboard, um Unregelmäßigkeiten bei der Abrechnung frühzeitig zu erkennen.

Credit-Based Billing Reference

Rollover, Overage-Modi, Ledger-Verwaltung und jeder Credit-API-Endpunkt.

Credit Webhook Events

Payload-Schemas für jedes Credit-Ereignis, das dein Server empfangen kann.
Zuletzt geändert am 26. September 2026