- Criar um entitlement de crédito personalizado para tokens e um medidor que faça deduções dele.
- Associar créditos a planos de assinatura, com e sem excesso de uso, e a um produto de recarga avulsa.
- Chamar a OpenAI a partir de um endpoint que cobra tokens por meio do Dodo Payments.
- Ler o saldo de créditos atual de um cliente com o SDK.
- Verificar assinaturas de webhook e encaminhar eventos de crédito do Dodo Payments.
O Que Estamos Construindo
A NeuralAPI vende três produtos:- Uma conta do Dodo Payments. Faça tudo no modo de teste.
- Uma chave de API da OpenAI.
- Node.js 22 ou posterior e conhecimento prático de TypeScript e Node.js.
Etapa 1: criar o entitlement de crédito de tokens
Crie o entitlement de crédito que será compartilhado pelos dois planos e pelo pacote de recarga. Ele define a unidade de token vendida pela NeuralAPI.
The Credits tab under Products shows all your credit entitlements.
Navigate to Credits
- Acesse o dashboard do Dodo Payments.
- Clique em Products na barra lateral.
- Selecione a aba Credits.
- Clique em Create Credit.
Configure the Credit Unit
API TokensCredit Type: Custom UnitUnit Name: tokenDefine Precision: 0. As contagens de tokens são números inteiros.Credit Expiry: 30 days. Os créditos expiram 30 dias após serem emitidos, o que corresponde ao ciclo de cobrança mensal.Skip Overage at the Credit Level
Save and Copy the Credit ID
cde_.API Tokens está pronto. Agora, crie um medidor para que os eventos de uso deduzam créditos.Etapa 2: criar um medidor para o uso de tokens
Um medidor agrega eventos de uso recebidos. Quando você o vincula a um crédito, o uso agregado é deduzido do saldo de créditos do cliente. Crie o medidor antes dos produtos de plano, pois você o associa ao criá-los na Etapa 3.Open the Meters Section
- Na barra lateral do dashboard, acesse Products → Meters.
- Clique em Create Meter.
Configure the Meter
Token Usage MeterEvent Name: api.tokens_used. Isso deve corresponder ao event_name enviado pelo seu app.Aggregation Type: Sum, para somar a contagem de tokens de cada evento.Over Property: tokens, a chave de metadados cujo valor é somado.Measurement Unit: tokensCrie o medidor. Você o selecionará pelo nome ao associá-lo aos produtos.Etapa 3: criar os produtos de plano
Crie os dois planos com o tipo de preço Usage Based Billing, não com Subscription simples. Os medidores são associados a produtos Usage Based Billing, e o medidor é o que deduz créditos conforme os clientes chamam sua API. Um produto Usage Based Billing ainda cobra uma tarifa base recorrente ($29 ou $99), e o uso adicional é cobrado em créditos.
Usage Based Billing pricing type with meter configuration.
Plano Starter ($29/mês — 10 milhões de tokens, sem excesso de uso)
Create the Starter Product
- Acesse Products e clique em Add Product.
- Em Pricing Type, selecione Usage Based Billing.
- Insira estes valores:
NeuralAPI StarterDescription: 10 million API tokens per month. Perfect for individual developers and small projects.Price: 29.00. Esta é a tarifa base recorrente, cobrada todos os meses mesmo antes de qualquer uso.Repeat payment every: 1 mêsCurrency: USDAttach the Meter
Token Usage Meter. Em seguida, configure o medidor:- Ative Bill usage in credits.
- Select credit:
API Tokens - Meter units per credit:
1. Cada token em um evento deduz um crédito. - Free Threshold:
0. O limite gratuito só se aplica quando um medidor cobra em dinheiro. Quando cobra em créditos, cada unidade é deduzida do saldo.

Toggle 'Bill usage in Credits' on the meter and pick the credit entitlement.
api.tokens_used recebidos deduzam o saldo do cliente.Configure Credit Issuance for Starter
10000000Import Default Credit Settings: ativado, para que o produto use a expiração de 30 dias do entitlement de crédito.Allow Overage: desativado. O padrão da Etapa 1 mantém o excesso de uso desativado, então os clientes Starter param em zero.
Configure credit issuance per cycle on the UBB product.
pdt_.Plano Pro ($99/mês — 40 milhões de tokens, excesso de uso ativado)
Create the Pro Product
NeuralAPI ProDescription: 40 million API tokens per month with overage. Built for production applications.Price: 99.00Repeat payment every: 1 mêsCurrency: USDAttach the Meter
Token Usage Meter, ative Bill usage in credits, selecione API Tokens e defina Meter units per credit como 1 e Free Threshold como 0.Configure Credit Issuance with Overage
40000000Import Default Credit Settings: desativado, para que você possa definir o excesso de uso para este produto.Allow Overage: ativadoPrice Per Unit: 0.000005 USD por token. Isso corresponde a $0.005 por 1 mil tokens, ou $5 por 1 milhão de tokens, valor superior à taxa efetiva por token do plano e que desestimula o excesso de uso.Overage Behavior: Bill overage at billing. O excesso de uso é cobrado na próxima fatura e, depois, o saldo é redefinido.Salve o produto e copie seu ID.Etapa 4: criar o pacote de recarga de tokens
O pacote de recarga é uma compra avulsa que adiciona 5.000.000 de tokens ao saldo de um cliente existente.
One-time pricing selected for a credit product.
Create a One-Time Product
- Acesse Products e clique em Add Product.
- Em Pricing Type, selecione One Time.
- Insira estes valores:
Token Top-Up PackDescription: Add 5 million tokens to your NeuralAPI balance.Price: 19.00Currency: USDAttach the Token Credit
- Na seção Entitlements, clique em Attach ao lado de Credits.
- Selecione
API Tokens. - Defina No of credits issued como
5000000. - Desative Import Default Credit Settings para substituir a expiração padrão de 30 dias.
- Defina Credit Expiry como Custom e insira
365dias. - Salve o produto.
Etapa 5: criar o backend
Crie o servidor Express. Ele cria checkouts de assinatura e de recarga, chama a OpenAI e cobra os tokens, lê saldos e recebe eventos de crédito por webhook.Set Up Your Project
tsconfig.json:package.json:Set Up Environment Variables
.env com uma chave de API do modo de teste em Developer → API Keys e os IDs das etapas anteriores:DODO_PAYMENTS_WEBHOOK_KEY na Etapa 7, depois de registrar o endpoint do webhook.Implement the Server
src/server.ts. O endpoint de completion chama o modelo gpt-6-luna da OpenAI, adequado para solicitações de alto volume. A aba package.json mostra a lista completa de dependências:How Deductions Happen
- Seu handler chama a OpenAI e lê
usage.total_tokens, por exemplo, 1532. - Você ingere um evento de uso com
event_name: api.tokens_usedemetadata: { tokens: 1532 }. - O
Token Usage Meteragrega eventos por cliente. Um worker em segundo plano processa novos eventos a cada minuto. - Como o meter cobra o crédito
API Tokenspor meio de Bill usage in credits, Dodo Payments deduz 1532 créditos, começando pelo grant do cliente que expira primeiro (FIFO). - Se o overage estiver habilitado e o saldo acabar, o déficit será rastreado e cobrado na próxima invoice.
Etapa 6: Adicione um Frontend de Demonstração
Criepublic/index.html para testar todos os fluxos no navegador. A página salva o ID do cliente em localStorage, para que subscribe, generate e top-up compartilhem uma identidade, como fariam em um app com login:
Etapa 7: Configure o Webhook
Webhooks permitem que seu servidor reaja a alterações de saldo, por exemplo, enviando um e-mail a um cliente cujo saldo esteja acabando.Expose Your Local Server
ngrok-free.app.Register the Webhook in Dodo Payments
- No dashboard, acesse Developer → Webhooks e clique em Add endpoint.
- Insira a URL
https://your-tunnel.ngrok-free.app/webhooks/dodo, usando o host do seu próprio túnel. - Selecione pelo menos estes eventos:
credit.addedcredit.deductedcredit.overage_charged
- Clique em Create endpoint e copie o signing secret da aba Overview do endpoint.
- Cole-o em
.envcomoDODO_PAYMENTS_WEBHOOK_KEYe reinicienpm run dev.
Etapa 8: Teste o Fluxo Completo
Subscribe a Test Customer
- Execute
npm run dev. - Abra
http://localhost:3000. - Selecione Pro, insira um endereço de e-mail e um nome de teste e clique em Get Checkout Link. Conclua o checkout usando os dados do cartão de teste.
- No dashboard, acesse Customers, abra o cliente mais recente e copie o ID, que começa com
cus_. - Cole o ID no campo Logged-in customer ID da demonstração e clique em Save.
Generate an AI Response
total_tokens real, ingere um evento de uso e retorna a resposta.Test the Top-Up Flow
credit.added.Solução de problemas
Credits not deducting after usage events
Credits not deducting after usage events
- O nome do evento do meter não corresponde ao
event_nameenviado por você.api.tokens_useddiferencia maiúsculas de minúsculas. - O meter não está vinculado ao crédito
API Tokensdo produto. Abra a configuração do meter do produto e confirme se Bill usage in credits está ativado. - A chave
metadata.tokensnão corresponde à propriedade Over Property do meter. - O grant do cliente expirou. Verifique o histórico de créditos do cliente.
- Em Products → Meters, abra o meter e confirme se o anexo do produto mostra o nome do crédito vinculado.
- Abra a aba Events do meter. Os eventos ingeridos aparecem ali mesmo antes de qualquer dedução.
- Abra o cliente em Customers e selecione a aba Credits. As entradas do ledger aparecem em um ou dois minutos.
Balance always shows 0 or 'customer not found'
Balance always shows 0 or 'customer not found'
- O cliente não concluiu o checkout. Os créditos são emitidos somente após um pagamento bem-sucedido.
- Você está consultando com o
customer_idincorreto. Use o ID que começa comcus_no dashboard, não um ID do seu próprio banco de dados. CREDIT_ENTITLEMENT_IDem.envnão corresponde ao crédito vinculado ao produto.
Overage not working for Pro plan customers
Overage not working for Pro plan customers
- O overage não está habilitado no credit attachment do produto Pro. A configuração no crédito é apenas um padrão.
- O cliente está no Starter, não no Pro.
- Overage Limit está definido como 0.
0.000005 ($5 por milhão de tokens). Verifique os zeros à esquerda: o campo aceita um preço por token, não por 1K tokens.Webhook verification failed in logs
Webhook verification failed in logs
- Ordem de análise do body:
express.json()foi executado em/webhooks/dodoantes deexpress.raw(). O SDK precisa dos bytes brutos da solicitação, não de JSON analisado. DODO_PAYMENTS_WEBHOOK_KEYcontém o signing secret incorreto.- Um proxy reverso reescreve os cabeçalhos da solicitação.
app.use('/webhooks/dodo', express.raw(...)) vem antes de app.use(express.json()) em server.ts.Precisa de ajuda?
Parabéns! Você criou o Billing baseado em créditos para a NeuralAPI
A NeuralAPI agora cobra em créditos, do checkout à dedução:Token Credit Entitlement
API Tokens reutilizável com prazo de expiração de 30 dias, compartilhado por ambos os planos e pelo pacote de top-up.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) encaminhados por um handler que verifica assinaturas com o helper Standard Webhooks do SDK.- Adicione autenticação a
/credits/:customerIde/api/generate. Como está escrito, qualquer pessoa pode chamá-los com qualquer ID de cliente. Autentique os usuários e consulte o ID do cliente no servidor. - Use valores estáveis de
event_id. O exemplo usaDate.now()mais uma string aleatória. Em produção, use o ID da sua solicitação para que as tentativas sejam idempotentes: Dodo Payments ignora um evento cujoevent_idjá tenha sido ingerido. - Armazene o mapeamento entre cliente e usuário. Salve
customer_idno seu banco de dados após o primeiro checkout, para que os usuários não precisem colá-lo manualmente. - Decida o que acontece quando uma assinatura termina. Os créditos do plano permanecem no ledger do cliente até expirarem, 30 dias após a emissão, e os créditos de top-up permanecem válidos por 365 dias. O
/api/generatedo tutorial verifica apenas o saldo, não o status da assinatura, portanto um cliente que cancelou ainda pode usar os tokens restantes. Esse é o padrão mais conveniente para o cliente. Para um acesso mais restrito, (a) escute o webhooksubscription.cancellede controle o acesso de/api/generatecom base no status da assinatura ou (b), após o cancelamento, debite os créditos não utilizados do plano com a API do ledger. As deduções usam o grant que expira primeiro, portanto os créditos do plano de 30 dias são usados antes dos créditos de top-up de 365 dias. - Monitore o dashboard de Usage Billing para detectar anomalias de metering rapidamente.