- Crear un entitlement de crédito personalizado (tokens) y un medidor que descuente créditos automáticamente
- Asociar créditos a planes de suscripción (con y sin exceso de uso) y a un producto de recarga de un solo pago
- Conectar un endpoint real de completado de OpenAI que facture los tokens mediante Dodo Payments
- Consultar el saldo de créditos actual de un cliente mediante el SDK
- Verificar firmas de webhook y enrutar eventos de crédito de Dodo Payments
Lo que vamos a crear
Este es el modelo de precios de NeuralAPI:- Una cuenta de Dodo Payments (el modo de prueba es suficiente)
- Una clave de API de OpenAI
- Node.js 18+
- Conocimientos básicos de TypeScript/Node.js
Paso 1: Crea tu entitlement de crédito de tokens
Primero, crea el entitlement de crédito que compartirán ambos planes de suscripción y el paquete de recarga. Piensa en esto como la definición de la unidad de «token» que utiliza tu plataforma.
The Credits tab under Products shows all your credit entitlements.
Navigate to Credits
- Inicia sesión en tu panel de Dodo Payments
- Haz clic en Products en la barra lateral izquierda
- Selecciona la pestaña Credits
- Haz clic en Create Credit
Configure the credit unit
API TokensTipo de crédito: selecciona Custom UnitNombre de la unidad: tokenPrecisión: 0 (los tokens siempre son números enteros)Caducidad del crédito: 30 days (los créditos se restablecen en cada ciclo de facturación)Skip overage at the credit level
Save and copy the credit ID
cent_xxxxxxxxxxxx.API Tokens está listo. A continuación, crea un medidor para que los eventos de uso activen los descuentos automáticamente.Paso 2: Crea un medidor para el uso de tokens
Un medidor agrega los eventos de uso entrantes y los convierte en descuentos de créditos. Lo necesitas antes de crear los productos de los planes, ya que lo asociarás durante la creación del producto en el paso 3.Open the Meters section
- En la barra lateral del panel, ve a Products → Meters
- Haz clic en Create Meter
Configure the meter
Token Usage MeterNombre del evento: api.tokens_used (debe coincidir exactamente con lo que envía tu aplicación)Tipo de agregación: Sum; sumamos el recuento de tokens de cada eventoSobre la propiedad: tokens; la clave de metadata de cada evento cuyo valor se sumaráUnidad de medición: tokensGuarda el medidor y copia su ID; lo necesitarás al asociarlo a los productos.Paso 3: Crea los productos de los planes
Ambos planes deben ser productos de Usage Based Billing, no simples productos de suscripción: los medidores solo se pueden asociar a productos UBB, y necesitas que el medidor descuente créditos automáticamente a medida que los clientes llaman a tu API. Los productos UBB siguen admitiendo una tarifa base recurrente ($29 / $99); el uso adicional se factura en créditos.

Usage Based Billing pricing type with meter configuration.
Plan Starter ($29/mes — 10 M de tokens, sin exceso de uso)
Create the Starter UBB product
- Ve a Products → Create Product
- Selecciona Usage Based Billing como tipo de precios
- Completa lo siguiente:
NeuralAPI StarterDescripción: 10 million API tokens per month. Perfect for individual developers and small projects.Precio fijo: 29.00 (la tarifa base recurrente, que se factura mensualmente incluso antes de cualquier uso)Ciclo de facturación: MonthlyMoneda: USDAttach the meter
Token Usage Meter. Después, en el medidor:- Activa Bill usage in Credits
- Entitlement de crédito: selecciona
API Tokens - Unidades del medidor por crédito:
1; cada token del evento equivale a 1 crédito descontado - Umbral gratuito:
0; la asignación de créditos es el «nivel gratuito» del cliente, por lo que no necesitamos una banda gratuita adicional

Toggle 'Bill usage in Credits' on the meter and pick the credit entitlement.
api.tokens_used entrantes descuenten realmente el saldo del cliente.Configure credit issuance for Starter
10000000Permitir exceso de uso: Deshabilitado; los clientes de Starter quedan bloqueados cuando se agotan los tokensImportar configuración de crédito predeterminada: Habilitado; utiliza la caducidad de 30 días del entitlement de crédito
Configure credit issuance per cycle on the UBB product.
Plan Pro ($99/mes — 40 M de tokens, exceso de uso habilitado)
Create the Pro UBB product
NeuralAPI ProDescripción: 40 million API tokens per month with overage. Built for production applications.Precio fijo: 99.00Ciclo de facturación: MonthlyMoneda: USDAttach the meter
Token Usage Meter, activa Bill usage in Credits, selecciona API Tokens, establece Unidades del medidor por crédito en 1 y Umbral gratuito en 0.Configure credit issuance with overage
40000000Importar configuración de crédito predeterminada: Deshabilitar; necesitamos personalizar la configuración del exceso de uso por productoPermitir exceso de uso: HabilitadoPrecio por unidad: 0.000005 USD por token (es decir, 5 por cada millón de tokens; por encima de la tarifa efectiva por token del plan para desincentivar el consumo excedente)Comportamiento del exceso de uso: Bill overage at billing; el exceso de uso se cobra en la siguiente factura y después el saldo se restableceGuarda el producto y copia su ID.Paso 4: Crea el paquete de recarga de tokens
El paquete de recarga es una compra única que añade 5.000.000 de tokens al saldo de un cliente existente.
Single Payment pricing selected for a one-time credit product.
Create a one-time product
- Ve a Products → Create Product
- Selecciona Single Payment como tipo de precios
- Completa lo siguiente:
Token Top-Up PackDescripción: Instantly add 5 million tokens to your NeuralAPI balance.Precio: 19.00Moneda: USDAttach the token credit
- En la sección Entitlements, haz clic en Attach junto a Credits
- Selecciona
API Tokens - Establece Créditos emitidos:
5000000 - Deshabilita Import Default Credit Settings; queremos anular la caducidad predeterminada de 30 días
- Establece Caducidad del crédito:
365 days - Guarda el producto
Paso 5: Crea el backend
Ahora crearemos el servidor Express que gestiona el checkout de suscripciones, el checkout de recargas, los completados reales de OpenAI con facturación por tokens, las consultas de saldo y los eventos de webhook de créditos.Set up your project
tsconfig.json:package.json:Set up environment variables
.env con tus credenciales y los ID de los pasos anteriores:DODO_PAYMENTS_WEBHOOK_KEY en el paso 7, después de registrar tu endpoint de webhook.Implement the server
src/server.ts:A note on how deductions actually happen
- Tu handler llama a OpenAI y obtiene
usage.total_tokens(por ejemplo, 1532). - Ingestas un único evento de uso:
event_name: api.tokens_used,metadata: { tokens: 1532 }. Token Usage Meteragrega los eventos por cliente.- Como el medidor está conectado al crédito
API Tokenscon Bill usage in Credits, Dodo Payments descuenta 1532 créditos de la asignación no caducada más antigua del cliente (FIFO). - Si el exceso de uso está habilitado y el cliente baja de cero, el déficit se registra y se factura en la siguiente factura.
Paso 6: Añade un frontend de demostración
Creapublic/index.html para probar todos los flujos en el navegador. Guardamos el ID del cliente en localStorage para que suscribirse → generar → recargar compartan la misma identidad, imitando una aplicación con sesión iniciada:
Paso 7: Conecta el webhook
Los webhooks permiten que tu servidor reaccione a los cambios de saldo; los usarás para enviar correos de «saldo bajo» antes de que los clientes lleguen a cero.Expose your local server
https://...ngrok-free.app.Register the webhook in Dodo Payments
- En el panel, ve a Developers → Webhooks → Add Endpoint
- URL:
https://your-tunnel.ngrok-free.app/webhooks/dodo - Suscríbete como mínimo a:
credit.addedcredit.deductedcredit.overage_charged
- Guarda y copia el Signing Secret
- 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 Plan Pro, introduce un correo y un nombre de prueba, haz clic en Get Checkout Link y completa el checkout con datos de tarjeta de prueba
- En el panel, ve a Customers → most recent y copia el ID de
cus_... - Pégalo en el campo «Logged-in customer ID» de la demostración y haz clic en Save
Generate a real 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 medidor no coincide con el
event_nameque estás enviando (api.tokens_useddistingue entre mayúsculas y minúsculas) - El medidor no está vinculado al crédito
API Tokensdel producto; ve a la configuración del medidor del producto y confirma que Bill usage in Credits esté habilitado - La clave
metadata.tokensno coincide con el campo «Over Property» del medidor - La asignación del cliente ha caducado (consulta el historial de créditos del cliente)
- Products → Meters: abre el medidor y confirma que muestre el nombre del crédito vinculado en la asociación del producto
- La pestaña Events del medidor; los eventos ingeridos deberían aparecer allí incluso antes del descuento
- Customers → [Customer] → Credits: las entradas del ledger deberían aparecer en uno o dos minutos
Balance always shows 0 or 'customer not found'
Balance always shows 0 or 'customer not found'
- El cliente aún no ha completado el checkout; los créditos solo se emiten después de un pago correcto
- Estás consultando con el
customer_idincorrecto (utiliza el IDcus_...del panel, no el ID de tu propia base de datos) - El
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 de uso no se habilitó en la asociación de crédito del producto Pro (la configuración del nivel de crédito solo es un valor predeterminado)
- El cliente está realmente en Starter, no en Pro
- El límite de exceso de uso se estableció en 0
0.000005 (= $5 por cada millón de tokens; comprueba los ceros iniciales: el campo acepta el precio por token, no por cada 1.000 tokens).`Webhook verification failed` in logs
`Webhook verification failed` in logs
- Orden del análisis del cuerpo:
express.json()se aplicó a/webhooks/dodoantes queexpress.raw(); el SDK necesita los bytes sin procesar de la solicitud, no JSON analizado - Secreto de firma incorrecto en
DODO_PAYMENTS_WEBHOOK_KEY - El proxy inverso está reescribiendo los encabezados
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
Tu plataforma ahora cuenta con un sistema completo de facturación de créditos listo para producción:Token Credit Entitlement
API Tokens reutilizable con una caducidad de 30 días, compartido entre todos los planes y el paquete de recargaTiered 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) enrutados mediante un handler cuya firma se verifica utilizando el helper Standard Webhooks del SDK- Autenticación en
/credits/:customerIdy/api/generate; actualmente cualquiera puede acceder a ellos con cualquier ID de cliente. Autentica a los usuarios y busca su ID de cliente en el servidor. event_ids estables; el ejemplo utilizaDate.now() + random. En producción, usa el ID de tu solicitud para que los reintentos sean idempotentes (Dodo Payments deduplica porevent_id).- Persistencia de la relación cliente↔usuario; guarda
customer_iden tu base de datos después del primer checkout para no tener que pegarlo manualmente. - Decide qué ocurre cuando termina una suscripción. Los créditos del plan permanecen en el ledger del cliente hasta su caducidad natural (30 días desde su emisión) y los créditos de recarga son válidos durante 365 días; sin embargo,
/api/generatedel cookbook solo comprueba el saldo, no el estado de la suscripción. Por tanto, un cliente cancelado aún puede consumir los tokens restantes. Ese es el comportamiento predeterminado más favorable para el consumidor. Si quieres un control de acceso más estricto, (a) escucha el webhooksubscription.cancelledy controla/api/generatesegún el estado de la suscripción, o (b) llama a la API de ledger de Dodo para debitar los créditos no utilizados del plan al cancelar, dejando intactos los créditos de recarga. - Supervisa el panel de Usage Billing para detectar pronto anomalías en la medición.