Skip to main content
O Credit-Based Billing permite conceder aos clientes um saldo de créditos — chamadas de API, tokens, unidades de computação ou qualquer métrica personalizada — e deduzir desse saldo conforme eles usam seu serviço. Os créditos funcionam com todos os tipos de produto: assinaturas, compras únicas e cobrança baseada em uso.

What is Credit-Based Billing?

Credit-Based Billing gives you a flexible system to issue credit entitlements to customers as part of your products. Instead of charging per-use or limiting access through feature flags, you allocate a pool of credits that customers draw from as they use your service. Os créditos funcionam bem para:
  • AI and LLM platforms: Grant tokens or generation credits per plan tier
  • API services: Allocate API call credits with overage pricing
  • Infrastructure platforms: Issue compute hours or storage credits
  • Communication services: Provide message or minute credits per subscription
  • SaaS with consumption tiers: Bundle included usage into credit pools
Checkout showing included credits with the product purchase

Credits appear as entitlements on your products and show in checkout, customer portal, and subscription details.

Core Concepts

Credit Types

When creating a credit, you choose between two types:
Defina créditos em sua própria unidade — tokens, chamadas de API, horas de computação ou qualquer métrica relevante para seu produto. As unidades personalizadas usam a precisão definida por você (de 0 a 10 casas decimais).Best for: API calls, AI tokens, compute hours, storage units, messages

Credit Lifecycle

Credits follow a clear lifecycle from issuance through consumption:
1

Credits Issued

Os créditos são concedidos quando um cliente compra um produto (assinatura ou compra única) com entitlements de crédito associados. Para assinaturas, os créditos são concedidos novamente a cada ciclo de cobrança.
2

Credits Consumed

As customers use your service, credits are deducted. For usage-based products, meters automatically deduct credits based on real-time events. You can also deduct credits manually via the dashboard or API.
3

Credits Expire or Roll Over

At the end of the billing cycle (or after the configured expiry period), unused credits either expire or roll over to the next period based on your settings.
4

Overage Handling

Se os créditos acabarem no meio do ciclo, você pode permitir overage (uso contínuo além do saldo) e escolher como o overage será tratado: perdoá-lo, cobrá-lo ou transferir o déficit para o próximo ciclo.

Grant Sources

Credits can be granted from multiple sources:

Creating Credits

Create credit entitlements in the Products → Credits section of your dashboard. Each credit defines the unit, precision, expiry rules, and lifecycle behavior.
Credits listing page showing created credit entitlements

The Credits tab under Products shows all your credit entitlements.

1

Navigate to Credits

Go to Products in your dashboard and select the Credits tab. Click Create Credit to start.
2

Configure Basic Information

Insira um Credit Name — este é o identificador interno do crédito.
Credit creation form showing basic info, general settings, and subscription settings

The credit creation form with all configuration sections.

3

Set General Settings

Configure the credit type and display properties:
string
obrigatório
Choose Custom Unit or Fiat Credits.
  • Custom Unit: Defina sua própria métrica (tokens, chamadas de API, horas de computação). Requer um Unit Name (por exemplo, “Platform tokens”) e uma configuração de Precision.
  • Fiat Credits: Os créditos representam um valor monetário real. Requer a seleção de uma Unit Currency (USD, EUR, GBP, INR etc.).
string
Somente para créditos de Custom Unit. O rótulo que os clientes veem para este crédito (por exemplo, “AI Tokens” ou “API Calls”). Exibido no checkout e no Customer Portal.
number
Somente para créditos de unidade personalizada. Número de casas decimais permitidas, de 0 a 10:
  • 0: Números inteiros (melhor para itens contáveis, como chamadas de API)
  • 1: Uma casa decimal (0.0)
  • 2: Duas casas decimais (0.00) — padrão
  • 3: Três casas decimais (0.000)
  • Até 10: Para unidades de alta precisão (por exemplo, tokens fracionários ou micro-uso)
Precision cannot be changed after the credit is created.
string
How long credits remain valid after issuance:
  • 7 days, 30 days (default), 60 days, 90 days, Custom, or Never
Select Custom to specify a custom number of days (minimum 1).
4

Configure Subscription Settings (Optional)

These settings control credit behavior within recurring subscriptions:
boolean
Allow unused credits to carry forward to the next billing cycle. When enabled, configure:
  • Max Rollover Percentage (0–100%): Limita quanto pode ser transferido
  • Rollover Timeframe: Por quanto tempo os créditos transferidos permanecem válidos (por exemplo, 1 Month)
  • Max Rollover Count: Número máximo de transferências consecutivas antes que os créditos sejam perdidos
When Credits Run Out or Subscription Expires:
boolean
Let customers continue using your service after their credit balance reaches zero. When enabled, configure:
  • Overage Limit: Máximo de créditos que os clientes podem consumir além do saldo
  • Price Per Unit: Custo por crédito adicional quando o overage está ativado (com seletor de moeda)
string
obrigatório
Controls how overage is handled at the end of the billing cycle:
  • Forgive overage at reset (padrão): O uso além do limite de crédito é registrado, mas não é cobrado. O saldo é redefinido a cada ciclo.
  • Bill overage at billing: O uso além do limite de crédito é cobrado na próxima fatura; depois, o saldo é redefinido.
  • Carry over deficit: O uso além do limite de crédito é transferido como saldo negativo para o próximo ciclo.
  • Carry over deficit (auto-repay): O déficit é transferido e automaticamente compensado com novos créditos no próximo ciclo.
5

Create Credit

Click Create Credit to save. The credit is now available to attach to any product.
Your credit entitlement is ready. Attach it to products to start issuing credits to customers.
Start with simple settings - no rollover, no overage - and add complexity as you learn how customers use credits. Most settings can be updated at any time without affecting existing grants. Note that precision cannot be changed after a credit is created.

Attaching Credits to Products

Créditos são anexados aos produtos como direitos no fluxo de criação ou edição do produto. Você pode anexar até 5 créditos por produto. Créditos funcionam com todos os três tipos de precificação.

Subscription Products

For subscriptions, credits are issued per billing cycle and can be configured with proration, trial credits, and cycle-specific settings.
1

Create or Edit a Subscription Product

Go to Products → Create Product or edit an existing product. Select Subscription as the pricing type and configure your recurring price.
2

Open Entitlements Section

Expand the Entitlements section and click the Attach button next to Credits.
Product entitlements section showing Credits attach button

The Entitlements section in the product form with Credits, License Key, and Digital Product Delivery options.

3

Select Credits to Attach

An Add Credits panel opens. You can select an existing credit from the dropdown or click Create new credit to define one on the spot.
Add Credits panel with credit selection dropdown

The Add Credits panel lets you select existing credits or create new ones.

Você pode anexar até 5 créditos por produto. Cada crédito pode ter sua própria configuração.
4

Configure Credit Settings

For each attached credit, configure:
number
obrigatório
The number of credits granted to the customer each billing period.
number
Notifique quando o saldo ficar abaixo desta porcentagem (0–100). Útil para alertar os clientes antes que os créditos acabem.
number
Set a different credit amount for trial periods. Enable Expire trial credits after trial ends to revoke unused trial credits when the trial converts to a paid subscription.
boolean
Prorate remaining credits when a customer upgrades or downgrades their subscription plan.
boolean
Use the default rollover, overage, and expiry settings from the credit entitlement. Turn this off to customize settings specifically for this product.
Credit configuration form with billing cycle, trial, and proration settings

Credit configuration showing per-cycle amount, trial credits, proration, and custom settings.

5

Review and Add

Review the attached credit showing name, amount, and expiration. Click Add to Subscription to confirm.
Add Credits panel showing selected credit with details

Review attached credits before adding them to the subscription.

One-Time Payment Products

For one-time payments, credits are issued once at the time of purchase.
1

Create a One-Time Product

Create a product with Single Payment pricing type.
Product pricing section with Single Payment selected

Single Payment pricing selected for a one-time credit product.

2

Attach Credits

Open the Entitlements section and attach credits. Configure the number of credits issued (total one-time grant) on purchase.
One-time credit products are ideal for credit top-up packs, promotional bundles, or prepaid credit purchases.

Usage-Based Billing Products

For usage-based products, credits are linked to meters and automatically deducted based on real-time consumption events.
1

Create a Usage-Based Product

Select Usage Based Billing as the pricing type. Configure the base price and billing frequency.
Usage Based Billing pricing configuration

Usage Based Billing pricing type with meter configuration.

2

Add a Meter

Clique no botão + na seção Select meter para adicionar um meter. Uma assinatura pode ter até 50 meters.
Select Meter panel showing free threshold and credit toggle

The Select Meter panel with meter configuration and credit toggle.

3

Enable Credit Billing on the Meter

Toggle Bill usage in Credits to attach a credit to the meter. Select the credit entitlement from the dropdown.
number
Aplica-se somente quando o meter cobra em dinheiro. Quando o meter cobra em créditos, cada unidade é deduzida do saldo de crédito.
boolean
When enabled, meter usage deducts from the customer’s credit balance instead of charging per-unit.
number
obrigatório
The number of usage units required to deduct 1 credit. For example, if set to 1000, then 1,000 API calls consume 1 credit.
Meter configuration with credit selection and meter units per credit

Credit attached to a meter with per-unit conversion rate.

4

Configure Credit Issuance

Set the number of credits issued and optionally customize the credit settings for this product.
Credit configuration for UBB product

Configure how many credits to issue and whether to use default settings.

5

Verify Attachment

Once configured, the meter shows the attached credit name, unit price, and free threshold.
Configured meter showing credit attachment details

Meter with credit attached showing price, threshold, and credit name.

Quando os créditos são vinculados a meters, o sistema deduz créditos automaticamente com base nos eventos de uso ingeridos. Um worker em segundo plano processa os eventos a cada minuto, agrega-os de acordo com a configuração do meter e aplica a dedução FIFO (first-in, first-out) a partir dos grants não expirados do cliente, começando pelo grant que expira primeiro.

Credit Settings

Rollover

Rollover lets unused credits carry forward to the next billing cycle instead of expiring. Example: A customer has 200 unused credits at cycle end. With 75% rollover, 150 credits carry forward and 50 are forfeited.

Overage

Overage controls what happens when a customer’s credit balance reaches zero mid-cycle. Overage Behavior options:
O Dodo Payments não bloqueia o uso quando o saldo chega a zero. Se você não quiser que os clientes continuem usando o serviço sem créditos, verifique o saldo em sua aplicação antes de atender à solicitação. Escolha um comportamento de overage que corresponda ao seu modelo de cobrança. Forgive at reset é a opção padrão e mais simples.

Expiração

Créditos expirados criam uma entrada de ledger credit_expired. Se o rollover estiver ativado, a porcentagem de rollover será aplicada antes da expiração, e somente o restante expirará.

Cobrança baseada em uso com créditos

Quando os créditos são vinculados a meters de uso, o sistema cria um poderoso modelo de cobrança baseado em consumo. Os clientes recebem uma alocação de créditos, e os eventos de uso deduzem automaticamente valores de seus saldos.
Dashboard de Usage Billing mostrando tabela de eventos com créditos consumidos

The Usage Billing dashboard shows meter events with units consumed, credits consumed, and customer details.

Como funciona a dedução de créditos baseada em meters

  1. Sua aplicação envia eventos de uso: Cada evento inclui um ID do cliente, nome do evento e metadata
  2. Os meters agregam eventos: Usando a agregação Count, Sum, Max ou Last
  3. Os créditos são deduzidos automaticamente: Um worker em segundo plano processa os eventos a cada minuto, converte unidades do meter em créditos usando a taxa configurada por você e deduz do saldo do cliente usando a ordenação FIFO (grants que expiram primeiro)
  4. O overage é rastreado: Se o saldo de crédito chegar a zero e o overage estiver ativado, o sistema rastreará o uso excedente para cobrança no fim do ciclo

Painel de Meters

O dashboard de Usage Billing inclui um painel de Meters que lista todos os meters definidos com seu tipo de agregação:

Experiência do cliente

Checkout

Quando um cliente compra um produto com créditos associados, a página de checkout exibe os créditos incluídos como parte da oferta do produto.
Página de checkout mostrando produto com créditos de chamadas de API incluídos

Checkout shows included credits with the product, making the value proposition clear.

Os créditos aparecem em uma seção Includes abaixo da descrição do produto, mostrando a quantidade e o tipo de crédito (por exemplo, “$1000 API calls”).

Customer Portal

Os clientes podem visualizar e gerenciar seus saldos de crédito no Customer Portal, na seção Credits.
Visualização de créditos do Customer Portal com saldo e histórico de transações

The Customer Portal shows available balance and full transaction history.

O portal exibe:
  • Available Balance: Saldo de crédito atual exibido em destaque
  • Credit Tabs: Alternância entre diferentes tipos de crédito (por exemplo, “OpenAI Credits” ou “Usage Tokens”)
  • Recent Transactions: Histórico completo com data, ID da transação, tipo, valor e saldo acumulado
Os tipos de transação exibidos aos clientes incluem:

Detalhes da assinatura

A página de detalhes da assinatura mostra os entitlements de crédito junto com outras informações do plano.
Página de detalhes da assinatura mostrando entitlements e histórico de uso

Subscription details show credit allocation, remaining balance, and renewal date.

Principais informações exibidas:
  • Credit allocation por ciclo de cobrança (por exemplo, “1000 credits each cycle”)
  • Remaining balance (por exemplo, “7500 credits remaining”)
  • Renewal date da próxima emissão de créditos
  • Aba Usage History com detalhamento por meter, mostrando unidades consumidas, limites, preços unitários e custos totais

Detalhes da transação

As páginas de transação de pagamento incluem uma seção Entitlements que mostra todos os entitlements entregues com o pagamento, incluindo créditos.
Página de detalhes da transação mostrando entitlements de crédito

Transaction details show credits alongside other entitlements like license keys and digital downloads.


Gerenciamento de créditos

Visualizações do dashboard

Lista de entitlements de crédito

Visualize todos os seus entitlements de crédito em Products → Credits. A tabela mostra o nome do crédito e as configurações de expiração, além de oferecer ações rápidas para edição ou arquivamento.
Página de listagem de créditos na seção Products

Credits listing with total count, creation button, and management actions.

Detalhes dos créditos do cliente

Visualize os saldos de crédito e o histórico de transações de um cliente específico em Customers → [Customer Name] → Credits.
Página de detalhes do cliente com a aba Credits mostrando saldo e transações

Customer detail page showing credit balance and full transaction ledger.

A visualização de créditos do cliente inclui:
  • Credit Selector - Alternância entre diferentes entitlements de crédito
  • Available Balance - Saldo atual exibido em tamanho grande e com destaque
  • Apply Credit/Debit - Botão para ajustar manualmente o saldo do cliente
  • Recent Transactions - Ledger completo com data, ID da transação, tipo, valor e saldo acumulado

Ajustes manuais

Você pode creditar ou debitar manualmente o saldo de um cliente diretamente pelo dashboard:
1

Navigate to Customer

Acesse Customers e selecione o cliente.
2

Open Credits Tab

Clique na aba Credits e selecione o entitlement de crédito apropriado no seletor de wallet.
3

Apply Credit or Debit

Clique em Apply Credit/Debit para abrir a interface de ajuste.
string
obrigatório
Selecione Credit para adicionar créditos ou Debit para removê-los do saldo do cliente.
number
obrigatório
A quantidade de créditos a adicionar ou remover.
string
Explicação opcional para o ajuste (por exemplo, “Service compensation” ou “Promotional bonus”).
4

Confirm

Revise e aplique o ajuste. A alteração é refletida imediatamente no saldo do cliente e registrada no credit ledger.
Os ajustes manuais criam uma entrada de ledger manual_adjustment com trilha de auditoria completa.

Credit Ledger

Cada operação de crédito é registrada no credit ledger, fornecendo uma trilha de auditoria completa: Cada entrada do ledger registra o saldo antes e depois da transação, o overage antes e depois, uma descrição e a referência à origem (pagamento, assinatura etc.).

Webhooks

O Credit-Based Billing dispara eventos de webhook para cada alteração no ciclo de vida dos créditos. Use-os para manter sua aplicação sincronizada com os saldos de crédito, disparar notificações ou criar workflows de cobrança personalizados. Todos os eventos do ledger (todos os eventos credit.*, exceto credit.balance_low) incluem o payload completo CreditLedgerEntry com o saldo antes/depois, o overage antes/depois, a referência da origem e o metadata da assinatura ou pagamento de origem do grant (vazio para grants criados diretamente pela API). O evento credit.balance_low inclui a configuração do limite e o saldo atual.

Credit Webhook Payloads

Visualize os schemas completos dos payloads, as descrições dos campos e exemplos de integração para todos os eventos de webhook de crédito.

Gerenciamento da API

Use a API para criar entitlements de crédito programaticamente, com controle total sobre as configurações de rollover, overage e expiração.

Create Credit Entitlement

Crie um novo entitlement de crédito com configurações de rollover, overage e expiração.

List Credit Entitlements

Recupere todos os entitlements de crédito da sua empresa.
Recupere, atualize ou exclua entitlements de crédito. Entitlements excluídos podem ser restaurados.

Get Credit Entitlement

Recupere um entitlement de crédito específico por ID.

Update Credit Entitlement

Atualize as configurações de rollover, overage, expiração ou outras.

Delete Credit Entitlement

Exclua logicamente um entitlement de crédito.

Undelete Credit Entitlement

Restaure um entitlement de crédito excluído anteriormente.
Conceda créditos diretamente ao saldo de um cliente sem exigir uma compra ou crie entradas de débito manuais para ajustes de cobrança.

Create Ledger Entry

Credite ou debite o saldo de um cliente com trilha de auditoria completa e suporte a idempotência.
Recupere o saldo de crédito atual de um cliente, o histórico de grants e o ledger completo de transações de qualquer entitlement de crédito.

List Balances

Liste todos os saldos de clientes de um entitlement de crédito.

Get Customer Balance

Obtenha o saldo de um cliente específico.

List Customer Grants

Visualize todos os grants de crédito de um cliente.

List Customer Ledger

Histórico completo de transações de um cliente.

Exemplo de integração

Inicialize o cliente Dodo Payments:
Associe créditos a um produto de assinatura durante o checkout:
Envie eventos de uso que deduzem créditos automaticamente:

Exemplos do mundo real

Estrutura de preços:Configuração:
  • Tipo de crédito: Custom Unit (“AI Tokens”)
  • Precisão: 0 (tokens inteiros)
  • Rollover: máximo de 25%, período de 1 mês
  • Overage: ativado, cobrar overage na cobrança
  • Meter: ai.generation com agregação Sum no campo tokens
Estrutura de preços:Configuração:
  • Tipo de crédito: Custom Unit (“API Calls”)
  • Precisão: 0 (chamadas inteiras)
  • Rollover: desativado
  • Overage: planos Developer+ permitem overage (perdoar na redefinição); o plano Free desativa o overage
  • Meter: api.request com agregação Count
Estrutura de preços:Configuração:
  • Tipo de crédito: Unidade personalizada (“GB-hours”)
  • Precisão: 2 (duas casas decimais)
  • Acúmulo: máximo de 50%, transferido uma vez
  • Excedente: Ativado, com um limite de excedente definido em GB-hours
  • Medidor: storage.usage com agregação por soma

Práticas recomendadas

  • Comece de forma simples: Comece com um único tipo de crédito e sem rollover. Adicione complexidade com base no feedback dos clientes e nos padrões de uso.
  • Defina expectativas claras: Exiba de forma destacada as alocações de crédito, os saldos restantes e os preços de overage nas páginas do produto e no Customer Portal.
  • Use unidades significativas: Dê aos créditos nomes que representem o que eles significam (por exemplo, “API Calls” ou “AI Tokens”), em vez de termos genéricos. Isso ajuda os clientes a entender o valor.
  • Configure a expiração com atenção: Períodos curtos de expiração (7 dias) aumentam o senso de urgência, mas podem frustrar os clientes. Períodos mais longos (30–90 dias) são mais adequados para a maioria dos produtos SaaS.
  • Monitore saldos baixos: Defina limites de saldo baixo para alertar os clientes antes que os créditos acabem, reduzindo cobranças inesperadas de overage.
  • Teste no modo de teste: Crie créditos, associe-os a produtos de teste e simule todo o ciclo de compra → uso → dedução → expiração antes de entrar em produção.
O Credit-Based Billing funciona com todos os outros recursos do Dodo Payments: assinaturas com trials, alterações de plano com proration e o Customer Portal. Comece com uma configuração básica e expanda à medida que seu modelo de preços evoluir.
Última modificação em 26 de setembro de 2026