Skip to main content
Per fare in modo che il tuo coding agent scriva l’integrazione, installa il Dodo Agent Plugin. Aggiunge le competenze e i server MCP di Dodo Payments a Claude Code, Codex CLI, Cursor, VS Code / GitHub Copilot, Kiro e OpenCode.
Costruirai NeuralAPI, un’API AI a livelli in cui ogni piano di abbonamento include una quantità mensile di crediti token. I clienti che stanno per esaurirli acquistano un pacchetto di ricarica e il tuo backend comunica i token utilizzati da ogni richiesta OpenAI, così Dodo Payments li detrae dal saldo del cliente.
Questo tutorial usa Node.js, Express e OpenAI SDK. I concetti di Dodo Payments (crediti, meter e webhook) funzionano allo stesso modo con qualsiasi framework o provider AI.
Al termine saprai come:
  • Creare un’entitlement di crediti personalizzato per i token e un meter che li detrae.
  • Collegare i crediti ai piani di abbonamento, con e senza overage, e a un prodotto di ricarica una tantum.
  • Chiamare OpenAI da un endpoint che addebita i token tramite Dodo Payments.
  • Leggere il saldo crediti aggiornato di un cliente con SDK.
  • Verificare le firme dei webhook e gestire gli eventi relativi ai crediti di Dodo Payments.

Cosa Stiamo Costruendo

NeuralAPI vende tre prodotti: Prima di iniziare, ti servono:
  • Un account Dodo Payments. Esegui tutto in modalità test.
  • Una chiave API OpenAI.
  • Node.js 22 o versioni successive e una conoscenza operativa di TypeScript e Node.js.

Passaggio 1: crea l’entitlement dei crediti token

Crea l’entitlement dei crediti condiviso da entrambi i piani e dal pacchetto di ricarica. Definisce l’unità token venduta da NeuralAPI.
Pagina dell'elenco dei crediti che mostra gli entitlement dei crediti creati

The Credits tab under Products shows all your credit entitlements.

1

Navigate to Credits

  1. Accedi alla dashboard di Dodo Payments.
  2. Fai clic su Products nella barra laterale.
  3. Seleziona la scheda Credits.
  4. Fai clic su Create Credit.
2

Configure the Credit Unit

Inserisci questi valori:Credit Name: API TokensCredit Type: Custom UnitUnit Name: tokenDefine Precision: 0. I conteggi dei token sono numeri interi.Credit Expiry: 30 days. I crediti scadono 30 giorni dopo l’emissione, in linea con il ciclo di fatturazione mensile.
La precisione non può essere modificata dopo la creazione del credito. Per i conteggi dei token, usa 0.
3

Skip Overage at the Credit Level

Lascia l’overage disabilitato sul credito. Lo configurerai per ogni piano quando colleghi il credito a ciascun prodotto, così il piano Starter può bloccare l’utilizzo a zero mentre il piano Pro consente l’overage.
Le impostazioni di overage sul credito sono valori predefiniti. Ogni collegamento a un prodotto può sovrascriverle, come avviene nel Passaggio 3 per il piano Pro.
4

Save and Copy the Credit ID

Fai clic su Create Credit. Apri il credito salvato e copia il relativo ID, che inizia con cde_.
L’entitlement dei crediti API Tokens è pronto. Ora crea un meter affinché gli eventi di utilizzo detraggano i crediti.

Passaggio 2: crea un meter per l’utilizzo dei token

Un meter aggrega gli eventi di utilizzo in ingresso. Quando lo colleghi a un credito, l’utilizzo aggregato viene detratto dal saldo crediti del cliente. Crea il meter prima dei prodotti piano, perché lo collegherai durante la loro creazione nel Passaggio 3.
1

Open the Meters Section

  1. Nella barra laterale della dashboard, vai a Products → Meters.
  2. Fai clic su Create Meter.
2

Configure the Meter

Inserisci questi valori:Meter Name: Token Usage MeterEvent Name: api.tokens_used. Deve corrispondere a event_name, che la tua app invia.Aggregation Type: Sum, per sommare il conteggio dei token di ogni evento.Over Property: tokens, la chiave dei metadati il cui valore viene sommato.Measurement Unit: tokens
I nomi degli eventi fanno distinzione tra maiuscole e minuscole: api.tokens_used e Api.Tokens.Used sono eventi diversi. Non puoi modificare un meter dopo averlo creato, quindi controlla ogni valore prima di confermare.
Crea il meter. Lo selezionerai per nome quando lo collegherai ai prodotti.
Il meter è stato creato. Ora collegalo al credito di ogni prodotto piano.

Passaggio 3: crea i prodotti piano

Crea entrambi i piani con il tipo di prezzo Usage Based Billing, non con il semplice tipo Subscription. I meter si collegano ai prodotti Usage Based Billing e sono i meter a detrarre i crediti quando i clienti chiamano la tua API. Un prodotto Usage Based Billing applica comunque una tariffa base ricorrente ($29 o $99), mentre l’utilizzo aggiuntivo viene addebitato in crediti.
Configurazione del prezzo Usage Based Billing

Usage Based Billing pricing type with meter configuration.

Piano Starter ($29/mese — 10 milioni di token, senza overage)

1

Create the Starter Product

  1. Vai a Products e fai clic su Add Product.
  2. In Pricing Type, seleziona Usage Based Billing.
  3. Inserisci questi valori:
Product Name: NeuralAPI StarterDescription: 10 million API tokens per month. Perfect for individual developers and small projects.Price: 29.00. Questa è la tariffa base ricorrente, addebitata ogni mese anche prima di qualsiasi utilizzo.Repeat payment every: 1 meseCurrency: USD
2

Attach the Meter

Nella sezione Select meter, fai clic su + e aggiungi Token Usage Meter. Configura quindi il meter:
  1. Attiva Bill usage in credits.
  2. Select credit: API Tokens
  3. Meter units per credit: 1. Ogni token in un evento detrae un credito.
  4. Free Threshold: 0. La soglia gratuita si applica solo quando un meter fattura in denaro. Quando fattura in crediti, ogni unità viene detratta dal saldo.
Meter con Bill usage in Credits attivato e API Tokens selezionato

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

È questo collegamento a fare in modo che gli eventi api.tokens_used in ingresso detraggano dal saldo del cliente.
3

Configure Credit Issuance for Starter

Dopo aver collegato un meter fatturato in crediti, nel prodotto viene mostrata una sezione di configurazione dei crediti. Inserisci:Credits issued per billing cycle: 10000000Import Default Credit Settings: attivato, così il prodotto utilizza la scadenza di 30 giorni dell’entitlement dei crediti.Allow Overage: disattivato. Il valore predefinito del Passaggio 1 mantiene l’overage disabilitato, quindi i clienti Starter si fermano a zero.
Modulo di configurazione dei crediti con importo per ciclo e impostazioni di overage

Configure credit issuance per cycle on the UBB product.

Salva il prodotto e copia il relativo ID, che inizia con pdt_.
Piano Starter: tariffa base di $29/mese, 10 milioni di token per ciclo, bloccato a zero e detratto tramite il meter.

Piano Pro ($99/mese — 40 milioni di token, overage attivato)

1

Create the Pro Product

Segui la procedura Starter con questi valori:Product Name: NeuralAPI ProDescription: 40 million API tokens per month with overage. Built for production applications.Price: 99.00Repeat payment every: 1 meseCurrency: USD
2

Attach the Meter

Configura il meter come per Starter: aggiungi Token Usage Meter, attiva Bill usage in credits, seleziona API Tokens e imposta Meter units per credit su 1 e Free Threshold su 0.
3

Configure Credit Issuance with Overage

Configura l’emissione dei crediti, questa volta con l’overage attivato:Credits issued per billing cycle: 40000000Import Default Credit Settings: disattivato, così puoi impostare l’overage per questo prodotto.Allow Overage: attivatoPrice Per Unit: 0.000005 USD per token. Corrisponde a $0.005 per 1.000 token, ovvero $5 per 1 milione di token, un valore superiore al costo effettivo per token del piano che scoraggia l’overage.Overage Behavior: Bill overage at billing. L’overage viene addebitato sulla fattura successiva, dopodiché il saldo viene azzerato.Salva il prodotto e copia il relativo ID.
Piano Pro: tariffa base di $99/mese, 40 milioni di token per ciclo, overage a $0.005 per 1.000 token e detrazione tramite il meter.

Passaggio 4: crea il pacchetto di ricarica token

Il pacchetto di ricarica è un acquisto una tantum che aggiunge 5.000.000 di token al saldo di un cliente esistente.
Sezione dei prezzi del prodotto con Single Payment selezionato

One-time pricing selected for a credit product.

1

Create a One-Time Product

  1. Vai a Products e fai clic su Add Product.
  2. In Pricing Type, seleziona One Time.
  3. Inserisci questi valori:
Product Name: Token Top-Up PackDescription: Add 5 million tokens to your NeuralAPI balance.Price: 19.00Currency: USD
2

Attach the Token Credit

  1. Nella sezione Entitlements, fai clic su Attach accanto a Credits.
  2. Seleziona API Tokens.
  3. Imposta No of credits issued su 5000000.
  4. Disattiva Import Default Credit Settings per sovrascrivere la scadenza predefinita di 30 giorni.
  5. Imposta Credit Expiry su Custom e inserisci 365 giorni.
  6. Salva il prodotto.
Copia l’ID del prodotto.
Perché una scadenza più lunga per le ricariche? I crediti dell’abbonamento scadono dopo 30 giorni perché questo è il ciclo di fatturazione. Una ricarica è un acquisto prepagato: il cliente ha pagato $19 in anticipo e si aspetta che i token durino più di un mese. Una scadenza di 365 giorni corrisponde al funzionamento dei crediti API prepagati di OpenAI e Anthropic, dove i crediti acquistati scadono un anno dopo l’acquisto, e limita comunque la tua responsabilità, impedendo ai clienti di accumulare crediti indefinitamente.
Il pacchetto di ricarica è configurato. Il suo acquisto assegna 5.000.000 di token validi per 365 giorni.

Passaggio 5: crea il backend

Crea il server Express. Il server crea le sessioni di checkout per abbonamenti e ricariche, chiama OpenAI e fattura i token, legge i saldi e riceve gli eventi webhook relativi ai crediti.
1

Set Up Your Project

Crea un tsconfig.json:
tsconfig.json
Aggiorna gli script di package.json:
package.json
2

Set Up Environment Variables

Crea .env con una chiave API in modalità test da Developer → API Keys e gli ID dei passaggi precedenti:
.env
Non eseguire mai il commit di .env nel controllo versione. Aggiungilo a .gitignore prima del primo commit.
Completerai DODO_PAYMENTS_WEBHOOK_KEY nel Passaggio 7, dopo aver registrato l’endpoint webhook.
3

Implement the Server

Crea src/server.ts per effettuare i test. L’endpoint completion chiama il modello gpt-6-luna di OpenAI, adatto alle richieste ad alto volume. La scheda package.json mostra l’elenco completo delle dipendenze:
Il backend è pronto: checkout dell’abbonamento, checkout della ricarica, una completion OpenAI con fatturazione dei token a consumo, la lettura del saldo e un webhook handler verificato.
@dodopayments/ingestion-blueprints fornisce tracker che effettuano per te la chiamata usageEvents.ingest, inclusi l’utilizzo di LLM Blueprint, API gateway, object storage, streams e time-range.
4

How Deductions Happen

Il server non chiama mai un endpoint “deduct N credits”. È il meter a effettuare la deduzione:
  1. Il tuo handler chiama OpenAI e legge usage.total_tokens, ad esempio 1532.
  2. Inoltri un singolo evento di utilizzo con event_name: api.tokens_used e metadata: { tokens: 1532 }.
  3. Token Usage Meter aggrega gli eventi per cliente. Un worker in background elabora i nuovi eventi ogni minuto.
  4. Poiché il meter fattura il credito API Tokens tramite Bill usage in credits, Dodo Payments deduce 1532 crediti, iniziando dal grant del cliente che scade per primo (FIFO).
  5. Se l’overage è abilitato e il saldo si esaurisce, il deficit viene tracciato e fatturato nella fattura successiva.
Il tuo codice si limita a inoltrare eventi.

Passaggio 6: Aggiungi un frontend demo

Crea public/index.html per testare ogni flusso nel browser. La pagina salva l’ID cliente in localStorage, quindi subscribe, generate e top-up condividono un’unica identità, come avverrebbe in un’app con utenti autenticati:

Passaggio 7: Configura il webhook

I webhook consentono al tuo server di reagire alle modifiche del saldo, ad esempio inviando un’email a un cliente il cui saldo si sta esaurendo.
1

Expose Your Local Server

I webhook richiedono un URL pubblico. Per lo sviluppo locale, usa ngrok o un altro tunnel:
Copia l’URL di forwarding HTTPS, che termina in ngrok-free.app.
2

Register the Webhook in Dodo Payments

  1. Nel dashboard, vai a Developer → Webhooks e fai clic su Add endpoint.
  2. Inserisci l’URL https://your-tunnel.ngrok-free.app/webhooks/dodo, utilizzando l’host del tuo tunnel.
  3. Seleziona almeno questi eventi:
    • credit.added
    • credit.deducted
    • credit.overage_charged
  4. Fai clic su Create endpoint, quindi copia il signing secret dalla scheda Overview dell’endpoint.
  5. Incollalo in .env come DODO_PAYMENTS_WEBHOOK_KEY, quindi riavvia npm run dev.
Il dodo.webhooks.unwrap() dell’SDK controlla gli header webhook-id, webhook-timestamp e webhook-signature con il tuo signing secret, quindi analizza il payload. Non scrivere un controllo HMAC personalizzato: Dodo Payments segue Standard Webhooks, che firma id.timestamp.body, non solo il body.

Passaggio 8: Testa il flusso completo

1

Subscribe a Test Customer

  1. Esegui npm run dev.
  2. Apri http://localhost:3000.
  3. Scegli Pro, inserisci un indirizzo email e un nome di test, quindi fai clic su Get Checkout Link. Completa il checkout con i dati della carta di test.
  4. Nel dashboard, vai a Customers, apri il cliente più recente e copia il suo ID, che inizia con cus_.
  5. Incolla l’ID nel campo Logged-in customer ID della demo e fai clic su Save.
Il cliente dispone di 40.000.000 di token. Fai clic su Refresh Balance per confermare.
2

Generate an AI Response

Inserisci un prompt e fai clic su Generate. Il server chiama OpenAI, legge il valore effettivo di total_tokens, inoltra un evento di utilizzo e restituisce la risposta.
Un worker in background elabora gli eventi di utilizzo ogni minuto, quindi il saldo non diminuisce subito. Attendi uno o due minuti, quindi fai nuovamente clic su Refresh Balance. Un saldo invariato al primo aggiornamento non significa che la misurazione non abbia funzionato.
3

Test the Top-Up Flow

Fai clic su Buy 5M Tokens — $19 e completa il checkout. Dopo che il pagamento è andato a buon fine, aggiorna il saldo: aumenta di 5.000.000 di token e il log del server mostra un evento credit.added.

Risoluzione dei problemi

Possibili cause:
  • Il nome dell’evento del meter non corrisponde a event_name, che invii. api.tokens_used distingue tra maiuscole e minuscole.
  • Il meter non è collegato al credito API Tokens del prodotto. Apri la configurazione del meter del prodotto e verifica che Bill usage in credits sia attivo.
  • La chiave metadata.tokens non corrisponde a Over Property del meter.
  • Il grant del cliente è scaduto. Controlla la cronologia dei crediti.
Cosa verificare:
  1. In Products → Meters, apri il meter e verifica che l’associazione al prodotto mostri il nome del credito collegato.
  2. Apri la scheda Events del meter. Gli eventi inoltrati vengono visualizzati lì anche prima di qualsiasi deduzione.
  3. Apri il cliente in Customers e seleziona la scheda Credits. Le voci del ledger vengono visualizzate entro uno o due minuti.
Possibili cause:
  • Il cliente non ha completato il checkout. I crediti vengono assegnati solo dopo un pagamento completato con successo.
  • Stai effettuando la query con customer_id errato. Usa l’ID che inizia con cus_ dal dashboard, non un ID del tuo database.
  • CREDIT_ENTITLEMENT_ID in .env non corrisponde al credito associato al prodotto.
Cosa verificare: Apri il cliente in Customers e seleziona la scheda Credits. Se non compaiono crediti, il credito non è stato associato al prodotto oppure il pagamento non è stato completato.
Possibili cause:
  • L’overage non è abilitato sull’associazione del credito del prodotto Pro. L’impostazione sul credito è solo un valore predefinito.
  • Il cliente usa Starter, non Pro.
  • Overage Limit è impostato su 0.
Cosa verificare: Modifica il prodotto Pro, apri il credito in Entitlements e verifica che Allow Overage sia attivo e che Price Per Unit sia 0.000005 ($5 per milione di token). Controlla gli zeri iniziali: il campo accetta un prezzo per token, non per 1K token.
Possibili cause:
  • Ordine di analisi del body: express.json() è stato eseguito su /webhooks/dodo prima di express.raw(). L’SDK richiede i raw bytes della richiesta, non il JSON analizzato.
  • DODO_PAYMENTS_WEBHOOK_KEY contiene il signing secret errato.
  • Un reverse proxy riscrive gli header della richiesta.
Cosa verificare: Verifica che la riga app.use('/webhooks/dodo', express.raw(...)) preceda app.use(express.json()) in server.ts.

Hai bisogno di aiuto?

Congratulazioni! Hai creato la fatturazione basata sui crediti per NeuralAPI

NeuralAPI ora fattura in crediti, dal checkout alla deduzione:

Token Credit Entitlement

Un credito API Tokens riutilizzabile con una scadenza di 30 giorni, condiviso da entrambi i piani e dal pacchetto di ricarica.

Tiered Plans, One Credit

Starter (10M token, limite rigido) e Pro (40M token più overage), configurati per prodotto senza duplicare il credito.

One-Time Top-Up Pack

I clienti aggiungono 5M token per $19 senza modificare il proprio abbonamento.

Deduction Through a Meter

I conteggi effettivi dei token OpenAI vengono inoltrati come eventi e il meter deduce i crediti in ordine FIFO, senza tracciamento manuale.

Live Balance API

Il saldo corrente, letto tramite l’SDK, per limitare l’accesso, mostrare l’utilizzo o avvisare i clienti nella tua app.

Verified Webhook Pipeline

Eventi del ledger dei crediti (credit.added, credit.deducted, credit.overage_charged) instradati tramite un handler che verifica le firme con l’helper Standard Webhooks dell’SDK.
Stai andando in produzione? Rafforza questi aspetti:
  • Aggiungi l’autenticazione a /credits/:customerId e /api/generate. Così come sono scritti, chiunque può chiamarli con qualsiasi ID cliente. Autentica gli utenti e recupera il loro ID cliente sul server.
  • Usa valori event_id stabili. L’esempio usa Date.now() più una stringa casuale. In produzione, usa l’ID della richiesta, così i retry sono idempotenti: Dodo Payments ignora un evento il cui event_id è già stato acquisito.
  • Salva la corrispondenza cliente-utente. Salva customer_id nel database dopo il primo checkout, così gli utenti non devono incollarlo manualmente.
  • Decidi cosa accade quando termina un abbonamento. I crediti del piano restano nel ledger del cliente fino alla loro scadenza, 30 giorni dopo l’assegnazione, mentre i crediti della ricarica restano validi per 365 giorni. /api/generate del tutorial controlla solo il saldo, non lo stato dell’abbonamento, quindi un cliente che ha annullato l’abbonamento può comunque utilizzare i token rimanenti. Questa è l’impostazione predefinita più favorevole al cliente. Per un accesso più restrittivo, puoi (a) ascoltare il webhook subscription.cancelled e subordinare /api/generate allo stato dell’abbonamento, oppure (b) al momento dell’annullamento, addebitare i crediti inutilizzati del piano tramite l’API del ledger. Le deduzioni vengono effettuate dal grant che scade per primo, quindi i crediti del piano con scadenza a 30 giorni vengono utilizzati prima dei crediti della ricarica con scadenza a 365 giorni.
  • Monitora il dashboard Usage Billing per individuare tempestivamente le anomalie di misurazione.

Credit-Based Billing Reference

Rollover, modalità di overage, gestione del ledger e ogni endpoint dell’API dei crediti.

Credit Webhook Events

Gli schemi dei payload per ogni evento di credito che il tuo server può ricevere.
Ultima modifica il 26 settembre 2026