- 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:- 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.
The Credits tab under Products shows all your credit entitlements.
Navigate to Credits
- Accedi alla dashboard di Dodo Payments.
- Fai clic su Products nella barra laterale.
- Seleziona la scheda Credits.
- Fai clic su Create Credit.
Configure the Credit Unit
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.Skip Overage at the Credit Level
Save and Copy the Credit ID
cde_.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.Open the Meters Section
- Nella barra laterale della dashboard, vai a Products → Meters.
- Fai clic su Create Meter.
Configure the Meter
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: tokensCrea il meter. Lo selezionerai per nome quando lo collegherai ai prodotti.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.
Usage Based Billing pricing type with meter configuration.
Piano Starter ($29/mese — 10 milioni di token, senza overage)
Create the Starter Product
- Vai a Products e fai clic su Add Product.
- In Pricing Type, seleziona Usage Based Billing.
- Inserisci questi valori:
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: USDAttach the Meter
Token Usage Meter. Configura quindi il meter:- Attiva Bill usage in credits.
- Select credit:
API Tokens - Meter units per credit:
1. Ogni token in un evento detrae un credito. - 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.

Toggle 'Bill usage in Credits' on the meter and pick the credit entitlement.
api.tokens_used in ingresso detraggano dal saldo del cliente.Configure Credit Issuance for Starter
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.
Configure credit issuance per cycle on the UBB product.
pdt_.Piano Pro ($99/mese — 40 milioni di token, overage attivato)
Create the Pro Product
NeuralAPI ProDescription: 40 million API tokens per month with overage. Built for production applications.Price: 99.00Repeat payment every: 1 meseCurrency: USDAttach the Meter
Token Usage Meter, attiva Bill usage in credits, seleziona API Tokens e imposta Meter units per credit su 1 e Free Threshold su 0.Configure Credit Issuance with Overage
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.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.
One-time pricing selected for a credit product.
Create a One-Time Product
- Vai a Products e fai clic su Add Product.
- In Pricing Type, seleziona One Time.
- Inserisci questi valori:
Token Top-Up PackDescription: Add 5 million tokens to your NeuralAPI balance.Price: 19.00Currency: USDAttach the Token Credit
- Nella sezione Entitlements, fai clic su Attach accanto a Credits.
- Seleziona
API Tokens. - Imposta No of credits issued su
5000000. - Disattiva Import Default Credit Settings per sovrascrivere la scadenza predefinita di 30 giorni.
- Imposta Credit Expiry su Custom e inserisci
365giorni. - Salva il prodotto.
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.Set Up Your Project
tsconfig.json:package.json:Set Up Environment Variables
.env con una chiave API in modalità test da Developer → API Keys e gli ID dei passaggi precedenti:DODO_PAYMENTS_WEBHOOK_KEY nel Passaggio 7, dopo aver registrato l’endpoint webhook.Implement the Server
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:How Deductions Happen
- Il tuo handler chiama OpenAI e legge
usage.total_tokens, ad esempio 1532. - Inoltri un singolo evento di utilizzo con
event_name: api.tokens_usedemetadata: { tokens: 1532 }. Token Usage Meteraggrega gli eventi per cliente. Un worker in background elabora i nuovi eventi ogni minuto.- Poiché il meter fattura il credito
API Tokenstramite Bill usage in credits, Dodo Payments deduce 1532 crediti, iniziando dal grant del cliente che scade per primo (FIFO). - Se l’overage è abilitato e il saldo si esaurisce, il deficit viene tracciato e fatturato nella fattura successiva.
Passaggio 6: Aggiungi un frontend demo
Creapublic/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.Expose Your Local Server
ngrok-free.app.Register the Webhook in Dodo Payments
- Nel dashboard, vai a Developer → Webhooks e fai clic su Add endpoint.
- Inserisci l’URL
https://your-tunnel.ngrok-free.app/webhooks/dodo, utilizzando l’host del tuo tunnel. - Seleziona almeno questi eventi:
credit.addedcredit.deductedcredit.overage_charged
- Fai clic su Create endpoint, quindi copia il signing secret dalla scheda Overview dell’endpoint.
- 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 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.
- Nel dashboard, vai a Customers, apri il cliente più recente e copia il suo ID, che inizia con
cus_. - Incolla l’ID nel campo Logged-in customer ID della demo e fai clic su Save.
Generate an AI Response
total_tokens, inoltra un evento di utilizzo e restituisce la risposta.Test the Top-Up Flow
credit.added.Risoluzione dei problemi
Credits not deducting after usage events
Credits not deducting after usage events
- Il nome dell’evento del meter non corrisponde a
event_name, che invii.api.tokens_useddistingue tra maiuscole e minuscole. - Il meter non è collegato al credito
API Tokensdel prodotto. Apri la configurazione del meter del prodotto e verifica che Bill usage in credits sia attivo. - La chiave
metadata.tokensnon corrisponde a Over Property del meter. - Il grant del cliente è scaduto. Controlla la cronologia dei crediti.
- In Products → Meters, apri il meter e verifica che l’associazione al prodotto mostri il nome del credito collegato.
- Apri la scheda Events del meter. Gli eventi inoltrati vengono visualizzati lì anche prima di qualsiasi deduzione.
- Apri il cliente in Customers e seleziona la scheda Credits. Le voci del ledger vengono visualizzate entro uno o due minuti.
Balance always shows 0 or 'customer not found'
Balance always shows 0 or 'customer not found'
- Il cliente non ha completato il checkout. I crediti vengono assegnati solo dopo un pagamento completato con successo.
- Stai effettuando la query con
customer_iderrato. Usa l’ID che inizia concus_dal dashboard, non un ID del tuo database. CREDIT_ENTITLEMENT_IDin.envnon corrisponde al credito associato al prodotto.
Overage not working for Pro plan customers
Overage not working for Pro plan customers
- 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.
0.000005 ($5 per milione di token). Controlla gli zeri iniziali: il campo accetta un prezzo per token, non per 1K token.Webhook verification failed in logs
Webhook verification failed in logs
- Ordine di analisi del body:
express.json()è stato eseguito su/webhooks/dodoprima diexpress.raw(). L’SDK richiede i raw bytes della richiesta, non il JSON analizzato. DODO_PAYMENTS_WEBHOOK_KEYcontiene il signing secret errato.- Un reverse proxy riscrive gli header della richiesta.
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
API Tokens riutilizzabile con una scadenza di 30 giorni, condiviso da entrambi i piani e dal pacchetto di ricarica.Tiered Plans, One Credit
One-Time Top-Up Pack
Deduction Through a Meter
Live Balance API
Verified Webhook Pipeline
credit.added, credit.deducted, credit.overage_charged) instradati tramite un handler che verifica le firme con l’helper Standard Webhooks dell’SDK.- Aggiungi l’autenticazione a
/credits/:customerIde/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_idstabili. L’esempio usaDate.now()più una stringa casuale. In produzione, usa l’ID della richiesta, così i retry sono idempotenti: Dodo Payments ignora un evento il cuievent_idè già stato acquisito. - Salva la corrispondenza cliente-utente. Salva
customer_idnel 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/generatedel 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 webhooksubscription.cancellede subordinare/api/generateallo 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.