- Crear un derecho de crédito personalizado para tokens y un medidor que lo descuente.
- Asociar créditos a planes de suscripción, con y sin exceso de uso, y a un producto de recarga de un solo pago.
- Llamar a OpenAI desde un endpoint que factura los tokens mediante Dodo Payments.
- Leer el saldo de créditos actualizado de un cliente con el SDK.
- Verificar firmas de webhooks y dirigir los eventos de crédito de Dodo Payments.
Lo que vamos a crear
NeuralAPI vende tres productos:- Una cuenta de Dodo Payments. Realiza todo en modo de prueba.
- Una clave de API de OpenAI.
- Node.js 22 o posterior, y conocimientos prácticos de TypeScript y Node.js.
Paso 1: Crear el derecho de crédito de tokens
Crea el derecho de crédito que compartirán ambos planes y el paquete de recarga. Define la unidad de tokens que vende NeuralAPI.
The Credits tab under Products shows all your credit entitlements.
Navigate to Credits
- Inicia sesión en el dashboard de Dodo Payments.
- Haz clic en Products en la barra lateral.
- Selecciona la pestaña Credits.
- Haz clic en Create Credit.
Configure the Credit Unit
API TokensCredit Type: Custom UnitUnit Name: tokenDefine Precision: 0. Los recuentos de tokens son números enteros.Credit Expiry: 30 days. Los créditos caducan 30 días después de su emisión, lo que coincide con el ciclo de facturación mensual.Skip Overage at the Credit Level
Save and Copy the Credit ID
cde_.API Tokens está listo. A continuación, crea un medidor para que los eventos de uso descuenten créditos.Paso 2: Crear un medidor para el uso de tokens
Un medidor agrega los eventos de uso entrantes. Cuando lo vinculas a un crédito, el uso agregado se descuenta del saldo de créditos del cliente. Crea el medidor antes que los productos de planes, porque lo asociarás mientras los creas en el paso 3.Open the Meters Section
- En la barra lateral del dashboard, ve a Products → Meters.
- Haz clic en Create Meter.
Configure the Meter
Token Usage MeterEvent Name: api.tokens_used. Debe coincidir con event_name, que envía tu aplicación.Aggregation Type: Sum, para sumar el recuento de tokens de cada evento.Over Property: tokens, la clave de metadatos cuyo valor se suma.Measurement Unit: tokensCrea el medidor. Lo seleccionarás por nombre al asociarlo a los productos.Paso 3: Crear los productos de los planes
Crea ambos planes con el tipo de precio Usage Based Billing, no con Subscription simple. Los medidores se asocian a productos de Usage Based Billing, y el medidor es el que descuenta créditos cuando los clientes llaman a tu API. Un producto de Usage Based Billing sigue cobrando una tarifa base recurrente ($29 o $99), y el uso adicional se factura en créditos.
Usage Based Billing pricing type with meter configuration.
Starter Plan ($29/mes — 10M tokens, sin exceso de uso)
Create the Starter Product
- Ve a Products y haz clic en Add Product.
- En Pricing Type, selecciona Usage Based Billing.
- Introduce estos valores:
NeuralAPI StarterDescription: 10 million API tokens per month. Perfect for individual developers and small projects.Price: 29.00. Esta es la tarifa base recurrente, que se cobra cada mes incluso antes de cualquier uso.Repeat payment every: 1 mesCurrency: USDAttach the Meter
Token Usage Meter. Después configura el medidor:- Activa Bill usage in credits.
- Select credit:
API Tokens - Meter units per credit:
1. Cada token de un evento descuenta un crédito. - Free Threshold:
0. El umbral gratuito solo se aplica cuando un medidor factura dinero. Cuando factura créditos, cada unidad se descuenta del saldo.

Toggle 'Bill usage in Credits' on the meter and pick the credit entitlement.
api.tokens_used descuenten del saldo del cliente.Configure Credit Issuance for Starter
10000000Import Default Credit Settings: activado, para que el producto utilice la caducidad de 30 días del derecho de crédito.Allow Overage: desactivado. El valor predeterminado del paso 1 mantiene desactivado el exceso de uso, por lo que los clientes Starter se detienen al llegar a cero.
Configure credit issuance per cycle on the UBB product.
pdt_.Pro Plan ($99/mes — 40M tokens, exceso de uso activado)
Create the Pro Product
NeuralAPI ProDescription: 40 million API tokens per month with overage. Built for production applications.Price: 99.00Repeat payment every: 1 mesCurrency: USDAttach the Meter
Token Usage Meter, activa Bill usage in credits, selecciona API Tokens y establece Meter units per credit en 1 y Free Threshold en 0.Configure Credit Issuance with Overage
40000000Import Default Credit Settings: desactivado, para poder establecer el exceso de uso de este producto.Allow Overage: activadoPrice Per Unit: 0.000005 USD por token. Eso equivale a $0.005 por cada 1K tokens, o $5 por cada 1M tokens, un valor superior a la tarifa efectiva por token del plan que desincentiva el exceso de uso.Overage Behavior: Bill overage at billing. El exceso de uso se cobra en la siguiente factura y, después, el saldo se restablece.Guarda el producto y copia su ID.Paso 4: Crear el paquete de recarga de tokens
El paquete de recarga es una compra única que añade 5.000.000 tokens al saldo de un cliente existente.
One-time pricing selected for a credit product.
Create a One-Time Product
- Ve a Products y haz clic en Add Product.
- En Pricing Type, selecciona One Time.
- Introduce estos valores:
Token Top-Up PackDescription: Add 5 million tokens to your NeuralAPI balance.Price: 19.00Currency: USDAttach the Token Credit
- En la sección Entitlements, haz clic en Attach junto a Credits.
- Selecciona
API Tokens. - Establece No of credits issued en
5000000. - Desactiva Import Default Credit Settings para sobrescribir la caducidad predeterminada de 30 días.
- Establece Credit Expiry en Custom e introduce
365días. - Guarda el producto.
Paso 5: Crear el backend
Crea el servidor de Express. Este crea los checkouts de suscripción y de recarga, llama a OpenAI y factura los tokens, lee los saldos y recibe eventos de crédito mediante webhooks.Set Up Your Project
tsconfig.json:package.json:Set Up Environment Variables
.env con una clave de API de modo de prueba de Developer → API Keys y los IDs de los pasos anteriores:DODO_PAYMENTS_WEBHOOK_KEY en el paso 7, después de registrar el endpoint del webhook.Implement the Server
src/server.ts. El endpoint de completion llama al modelo gpt-6-luna de OpenAI, que es adecuado para solicitudes de gran volumen. La pestaña package.json muestra la lista completa de dependencias:How Deductions Happen
- Tu handler llama a OpenAI y lee
usage.total_tokens, por ejemplo 1532. - Ingestas un evento de uso con
event_name: api.tokens_usedymetadata: { tokens: 1532 }. Token Usage Meteragrega los eventos por cliente. Un worker en segundo plano procesa los eventos nuevos cada minuto.- Como el meter factura el crédito
API Tokensmediante Bill usage in credits, Dodo Payments deduce 1532 créditos, comenzando por la asignación del cliente que caduca primero (FIFO). - Si el exceso está habilitado y el saldo se agota, el déficit se registra y se factura en la siguiente invoice.
Paso 6: Añade un frontend de demostración
Creapublic/index.html para probar todos los flujos en tu navegador. La página guarda el ID del cliente en localStorage, de modo que suscribirse, generar y recargar compartan una misma identidad, como ocurriría en una aplicación con inicio de sesión:
Paso 7: Configura el webhook
Los webhooks permiten que tu servidor reaccione a los cambios de saldo, por ejemplo, para enviar un correo a un cliente cuyo saldo se está agotando.Expose Your Local Server
ngrok-free.app.Register the Webhook in Dodo Payments
- En el dashboard, ve a Developer → Webhooks y haz clic en Add endpoint.
- Introduce la URL
https://your-tunnel.ngrok-free.app/webhooks/dodousando el host de tu propio túnel. - Selecciona al menos estos eventos:
credit.addedcredit.deductedcredit.overage_charged
- Haz clic en Create endpoint y copia el signing secret de la pestaña Overview del endpoint.
- Pégalo en
.envcomoDODO_PAYMENTS_WEBHOOK_KEYy reinicianpm run dev.
Paso 8: Prueba el flujo completo
Subscribe a Test Customer
- Ejecuta
npm run dev. - Abre
http://localhost:3000. - Elige Pro, introduce un correo electrónico y un nombre de prueba, y haz clic en Get Checkout Link. Completa el checkout con datos de tarjeta de prueba.
- En el dashboard, ve a Customers, abre el cliente más reciente y copia su ID, que comienza por
cus_. - Pega el ID en el campo Logged-in customer ID de la demo y haz clic en Save.
Generate an AI Response
total_tokens real, ingesta un evento de uso y devuelve la respuesta.Test the Top-Up Flow
credit.added.Solución de problemas
Credits not deducting after usage events
Credits not deducting after usage events
- El nombre del evento del meter no coincide con el
event_nameque envías.api.tokens_useddistingue entre mayúsculas y minúsculas. - El meter no está vinculado al crédito
API Tokensdel producto. Abre la configuración del meter del producto y confirma que Bill usage in credits esté activado. - La clave
metadata.tokensno coincide con Over Property del meter. - La asignación del cliente ha caducado. Comprueba el historial de créditos del cliente.
- En Products → Meters, abre el meter y confirma que el vínculo del producto muestre el nombre del crédito asociado.
- Abre la pestaña Events del meter. Los eventos ingeridos aparecen allí incluso antes de cualquier deducción.
- Abre el cliente en Customers y selecciona la pestaña Credits. Las entradas del ledger aparecen en uno o dos minutos.
Balance always shows 0 or 'customer not found'
Balance always shows 0 or 'customer not found'
- El cliente no ha completado el checkout. Los créditos solo se emiten después de un pago exitoso.
- Estás consultando con el
customer_idincorrecto. Usa el ID que comienza porcus_del dashboard, no un ID de tu propia base de datos. CREDIT_ENTITLEMENT_IDen.envno coincide con el crédito asociado al producto.
Overage not working for Pro plan customers
Overage not working for Pro plan customers
- El exceso no está habilitado en la credit attachment del producto Pro. La configuración del crédito solo es un valor predeterminado.
- El cliente tiene el plan Starter, no Pro.
- Overage Limit está establecido en 0.
0.000005 ($5 por cada millón de tokens). Comprueba los ceros iniciales: el campo acepta un precio por token, no por 1K tokens.Webhook verification failed in logs
Webhook verification failed in logs
- Orden del análisis del body:
express.json()se ejecutó sobre/webhooks/dodoantes queexpress.raw(). El SDK necesita los bytes sin procesar de la solicitud, no JSON analizado. DODO_PAYMENTS_WEBHOOK_KEYcontiene el signing secret incorrecto.- Un proxy inverso reescribe los headers de la solicitud.
app.use('/webhooks/dodo', express.raw(...)) aparezca antes que app.use(express.json()) en server.ts.¿Necesitas ayuda?
¡Enhorabuena! Has creado la facturación basada en créditos para NeuralAPI
NeuralAPI ahora factura en créditos desde el checkout hasta la deducción:Token Credit Entitlement
API Tokens reutilizable con una caducidad de 30 días, compartido por ambos planes y el paquete de recarga.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) enviados a través de un handler que verifica las firmas con el helper Standard Webhooks del SDK.- Añade autenticación a
/credits/:customerIdy/api/generate. Tal como están escritos, cualquiera puede llamarlos con cualquier ID de cliente. Autentica a los usuarios y busca su ID de cliente en el servidor. - Usa valores estables de
event_id. El ejemplo utilizaDate.now()más una cadena aleatoria. En producción, usa el ID de tu solicitud para que los reintentos sean idempotentes: Dodo Payments ignora un evento cuyoevent_idya haya ingerido. - Guarda la relación entre el cliente y el usuario. Guarda
customer_iden tu base de datos después del primer checkout, para que los usuarios no tengan que pegarlo manualmente. - Decide qué ocurre cuando termina una suscripción. Los créditos del plan permanecen en el ledger del cliente hasta que caducan 30 días después de su emisión, y los créditos de recarga siguen siendo válidos durante 365 días. El
/api/generatedel tutorial solo comprueba el saldo, no el estado de la suscripción, por lo que un cliente cancelado todavía puede usar sus tokens restantes. Este es el valor predeterminado más favorable para el cliente. Para un acceso más estricto, (a) escucha el webhooksubscription.cancelledy controla/api/generatesegún el estado de la suscripción, o (b) cuando se cancele, carga los créditos no utilizados del plan mediante la API del ledger. Las cargas se descuentan de la asignación que caduca primero, por lo que los créditos del plan de 30 días se consumen antes que los créditos de recarga de 365 días. - Supervisa el dashboard de Usage Billing para detectar pronto las anomalías de medición.