In questo tutorial, creerai NeuralAPI — una piattaforma AI a livelli in cui ogni piano di abbonamento include un credito mensile di token, i clienti possono acquistare pacchetti di ricarica quando sono a corto di crediti, e il tuo backend detrae automaticamente i crediti mentre le richieste vengono elaborate da 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.
- Creare un diritto di credito personalizzato (token) e un misuratore che detrae automaticamente da esso
- Collegare i crediti ai piani di abbonamento (con e senza sforamento) e a un prodotto di ricarica una tantum
- Collegare un endpoint di completamento OpenAI reale che fattura i token tramite Dodo Payments
- Interrogare il saldo del credito live di un cliente tramite l’SDK
- Verificare le firme del webhook e indirizzare gli eventi di credito di Dodo Payments
Cosa Stiamo Costruendo
Ecco il modello di pricing per NeuralAPI:| Prodotto | Prezzo | Token | Sforamento |
|---|---|---|---|
| Piano Iniziale | $29/mese | 10,000,000 token/ciclo | Bloccato a zero |
| Piano Pro | $99/mese | 40,000,000 token/ciclo | $0.005 per 1K token |
| Pacchetto di Ricarica Token | $19 una tantum | +5,000,000 token | — |
- Un account Dodo Payments (va bene la modalità di test)
- Una chiave API OpenAI
- Node.js 18+
- Conoscenza di base di TypeScript/Node.js
Passaggio 1: Crea il Tuo Diritto di Credito Token
Per prima cosa, crea il diritto di credito che condivideranno entrambi i piani di abbonamento e il pacchetto di ricarica. Pensa a questo come alla definizione dell’unità “token” che utilizza la tua piattaforma.
Navigate to Credits
- Accedi alla tua dashboard di Dodo Payments
- Clicca su Prodotti nella barra laterale sinistra
- Seleziona la scheda Crediti
- Clicca su Crea Credito
Configure the credit unit
API TokensTipo di Credito: Seleziona Unità PersonalizzataNome Unità: tokenPrecisione: 0 (i token sono sempre numeri interi)Scadenza Credito: 30 days (i crediti si azzerano a ogni ciclo di fatturazione)Skip overage at the credit level
Passaggio 2: Crea un Misuratore per l’Uso dei Token
Un misuratore aggrega gli eventi di utilizzo in arrivo e li converte in detrazioni di credito. Ti serve questo prima di creare i prodotti del piano, poiché lo aggancerai durante la creazione del prodotto nel Passaggio 3.Open the Meters section
- Nella barra laterale della dashboard, vai su Prodotti → Misuratori
- Clicca su Crea Misuratore
Configure the meter
Token Usage MeterNome Evento: api.tokens_used (questo deve corrispondere esattamente a ciò che invia la tua app)Tipo di Aggregazione: Sum — sommiamo il conteggio dei token da ogni eventoSopra la Proprietà: tokens — la chiave dei metadati su ciascun evento il cui valore verrà sommatoUnità di Misura: tokensSalva il misuratore e copia il suo ID — lo citerai quando lo agganci ai prodotti.Passaggio 3: Crea i Prodotti del Piano
Entrambi i piani devono essere prodotti Usage Based Billing, non semplici Abbonamenti — i misuratori possono essere agganciati solo ai prodotti UBB, e hai bisogno del misuratore per detrarre automaticamente i crediti quando i clienti chiamano la tua API. I prodotti UBB supportano ancora una tariffa base ricorrente (la$29 / $99); l’uso al di sopra di tale soglia viene fatturato in crediti.

Piano Iniziale ($29/mese — 10M token, nessuno sforamento)
Create the Starter UBB product
- Vai su Prodotti → Crea Prodotto
- Seleziona Usage Based Billing come tipo di tariffazione
- Compila:
NeuralAPI StarterDescrizione: 10 million API tokens per month. Perfect for individual developers and small projects.Prezzo Fisso: 29.00 (la tariffa base ricorrente — fatturata mensilmente anche prima di qualsiasi utilizzo)Ciclo di Fatturazione: MonthlyValuta: USDAttach the meter
Token Usage Meter. Poi sul misuratore:- Attiva Fattura utilizzo in Crediti
- Diritto di Credito: seleziona
API Tokens - Unità di Misura per Credito:
1— ogni token nell’evento mappa a 1 credito detratto - Soglia Gratuita:
0— la stessa allocazione del credito è il “livello gratuito” del cliente; non abbiamo bisogno di una banda gratuita extra

api.tokens_used in arrivo detraggano effettivamente dal saldo del cliente.Configure credit issuance for Starter
10000000Consentire Sforamento: Disabilitato — i clienti Iniziali sono bloccati quando i token si esaurisconoImporta Impostazioni di Credito Predefinite: Abilitato — usa la scadenza di 30 giorni dal diritto di credito
Piano Pro ($99/mese — 40M token, sforamento abilitato)
Create the Pro UBB product
NeuralAPI ProDescrizione: 40 million API tokens per month with overage. Built for production applications.Prezzo Fisso: 99.00Ciclo di Fatturazione: MonthlyValuta: USDAttach the meter
Token Usage Meter, attiva Fattura utilizzo in Crediti, seleziona API Tokens, Unità di Misura per Credito 1, Soglia Gratuita 0.Configure credit issuance with overage
40000000Importa Impostazioni di Credito Predefinite: Disabilitato — dobbiamo personalizzare le impostazioni di sforamento per prodottoConsenti Sforamento: AbilitatoPrezzo per Unità: 0.000005 USD per token (cioè, 5 per 1M token — sopra la tariffa effettiva per token del piano per scoraggiare gli spurghi)Comportamento dello Sforamento: Bill overage at billing — lo sforamento viene addebitato sulla fattura successiva, quindi il saldo si azzeraSalva il prodotto e copia l’ID del prodotto.Passaggio 4: Crea il Pacchetto di Ricarica Token
Il pacchetto di ricarica è un acquisto una tantum che aggiunge 5,000,000 token al saldo di un cliente esistente.
Create a one-time product
- Vai su Prodotti → Crea Prodotto
- Seleziona Pagamento Singolo come tipo di tariffazione
- Compila:
Token Top-Up PackDescrizione: Instantly add 5 million tokens to your NeuralAPI balance.Prezzo: 19.00Valuta: USDAttach the token credit
- Nella sezione Diritti, clicca su Collega accanto a Crediti
- Seleziona
API Tokens - Imposta Crediti emessi:
5000000 - Disabilita Importa Impostazioni di Credito Predefinite — vogliamo sovrascrivere la scadenza predefinita di 30 giorni
- Imposta Scadenza Credito:
365 days - Salva il prodotto
Passaggio 5: Costruisci il Backend
Ora costruiamo il server Express che gestisce il checkout dell’abbonamento, il checkout della ricarica, i completamenti OpenAI reali con fatturazione dei token, le query del saldo e gli eventi di webhook del credito.Set up environment variables
.env con le tue credenziali e gli ID dai passaggi precedenti:DODO_PAYMENTS_WEBHOOK_KEY nel Passaggio 7 dopo aver registrato il tuo endpoint di webhook.Implement the server
src/server.ts:A note on how deductions actually happen
- Il tuo gestore chiama OpenAI e riceve
usage.total_tokens(es. 1532). - Inserisci un singolo evento di utilizzo:
event_name: api.tokens_used,metadata: { tokens: 1532 }. Token Usage Meteraggrega gli eventi per cliente.- Poiché il misuratore è collegato al credito
API Tokenscon Fattura utilizzo in Crediti, Dodo Payments detrae 1532 crediti dal grant non scaduto più vecchio del cliente (FIFO). - Se lo sforamento è abilitato e il cliente va sotto zero, il deficit viene tracciato e fatturato sulla fattura successiva.
Passaggio 6: Aggiungi un Frontend Demo
Creapublic/index.html per testare tutti i flussi nel tuo browser. Persistiamo l’ID cliente su localStorage in modo che abbonamento → generazione → ricarica condividano tutti la stessa identità, imitando un’app con accesso:
Passaggio 7: Collegare il Webhook
I webhook consentono al tuo server di reagire ai cambiamenti di saldo — li utilizzerai per inviare email di “saldo in esaurimento” prima che i clienti raggiungano lo zero.Expose your local server
https://...ngrok-free.app.Register the webhook in Dodo Payments
- Nella dashboard, vai su Sviluppatori → Webhook → Aggiungi Endpoint
- URL:
https://your-tunnel.ngrok-free.app/webhooks/dodo - Iscriviti a (al minimo):
credit.addedcredit.deductedcredit.overage_charged
- Salva e copia il Segreto della Firma
- Incollalo in
.envcomeDODO_PAYMENTS_WEBHOOK_KEY, quindi riavvianpm run dev
Passaggio 8: Testa il Flusso Completo
Subscribe a test customer
- Esegui
npm run dev - Apri
http://localhost:3000 - Scegli Piano Pro, inserisci un’email e un nome di test, clicca Ottieni Link per il Checkout, completa il checkout con dettagli della carta di test
- Nella dashboard, vai su Clienti → il più recente e copia l’ID
cus_... - Incollalo nel campo “ID cliente loggato” nel demo e clicca Salva
Generate a real AI response
total_tokens, inserisce un evento di utilizzo e restituisce la risposta.Risoluzione dei Problemi
Credits not deducting after usage events
Credits not deducting after usage events
- Il nome dell’evento del misuratore non corrisponde a
event_nameche stai inviando (api.tokens_usedè case-sensitive) - Il misuratore non è collegato al credito
API Tokenssul prodotto — vai alla configurazione del misuratore del prodotto e conferma che Fattura utilizzo in Crediti è attivato - La chiave
metadata.tokensnon corrisponde al campo “Sopra la Proprietà” del misuratore - Il grant del cliente è scaduto (controlla la cronologia dei crediti del cliente)
- Prodotti → Misuratori: apri il misuratore e conferma che mostra il nome del credito collegato sul collegamento del prodotto
- La scheda Eventi sul misuratore — gli eventi inseriti dovrebbero apparire lì anche prima della detrazione
- Clienti → [Cliente] → Crediti: le voci del registro dovrebbero apparire entro un minuto o due
Balance always shows 0 or 'customer not found'
Balance always shows 0 or 'customer not found'
- Il cliente non ha ancora completato il checkout — i crediti vengono emessi solo dopo un pagamento riuscito
- Stai interrogando con il
customer_idsbagliato (usa l’IDcus_...dalla dashboard, non il tuo ID DB) - Il
CREDIT_ENTITLEMENT_IDin.envnon corrisponde al credito attaccato al prodotto
Overage not working for Pro plan customers
Overage not working for Pro plan customers
- Lo sforamento non è stato abilitato sul collegamento del credito del prodotto Pro (l’impostazione a livello di credito è solo un predefinito)
- Il cliente è effettivamente sul Piano Iniziale, non sul Pro
- Il limite di sforamento è stato impostato a 0
0.000005 (= $5 per milione di token; ricontrolla gli zeri principali — il campo accetta il prezzo per token, non per 1K).`Webhook verification failed` in logs
`Webhook verification failed` in logs
- Ordine di parsing del corpo:
express.json()è stato applicato a/webhooks/dodoprima diexpress.raw()— l’SDK ha bisogno dei byte grezzi della richiesta, non del JSON parsato - Segreto di firma errato in
DODO_PAYMENTS_WEBHOOK_KEY - Il proxy inverso sta riscrivendo le intestazioni
app.use('/webhooks/dodo', express.raw(...)) venga prima di app.use(express.json()) in server.ts.Hai Bisogno di Aiuto?
Congratulazioni! Hai Costruito la Fatturazione Basata su Crediti per NeuralAPI
La tua piattaforma ora ha un sistema di fatturazione a crediti completo e pronto per la produzione:Token Credit Entitlement
API Tokens riutilizzabile con scadenza di 30 giorni, condiviso tra tutti i piani e il pacchetto di ricaricaTiered Plans, One Credit
One-Time Top-Up Pack
Auto-Deduction via Meter
Live Balance API
Verified Webhook Pipeline
credit.added, credit.deducted, credit.overage_charged) instradati tramite un gestore verificato dal SDK- Autenticazione su
/credits/:customerIde/api/generate— attualmente chiunque può colpire questi con qualsiasi ID cliente. Autentica gli utenti e cerca il loro ID cliente lato server. - Stable
event_ids — l’esempio utilizzaDate.now() + random. In produzione, usa il tuo ID richiesta in modo che i tentativi siano idempotenti (Dodo Payments deduplica perevent_id). - Mantieni la mappatura cliente↔utente — memorizza
customer_idnel tuo DB dopo il primo checkout in modo da non avere bisogno di un passaggio di copia manuale. - Decidi cosa succede quando un abbonamento termina. I crediti del piano rimangono nel registro del cliente fino alla loro scadenza naturale (30 giorni dall’emissione) e i crediti di ricarica restano validi per 365 giorni — ma il cookbook
/api/generatecontrolla solo saldo, non stato dell’abbonamento. Quindi un cliente annullato può ancora consumare i token rimanenti. Questo è il default amichevole per il consumatore. Se desideri un controllo dell’accesso più rigoroso, o (a) ascolta il webhooksubscription.cancellede regola/api/generatein base allo stato dell’abbonamento, o (b) chiama l’API del registro di Dodo per addebitare i crediti inutilizzati del piano in caso di cancellazione lasciando intatti i crediti di ricarica. - Monitora il dashboard Usage Billing per rilevare precocemente anomalie di misurazione.