Pular para o conteúdo principal
Os medidores convertem eventos brutos em quantidades faturáveis. Eles filtram eventos e aplicam funções de agregação (Count, Sum, Max, Last) para calcular o uso por cliente.
Interface de criação de medidor mostrando o nome do evento, tipo de agregação e opções de filtragem

​
Recursos da API

Create Meter

Crie medidores programaticamente via API.

List Meters

Recupere todos os medidores em sua conta.

Get Meter

Obtenha detalhes de um medidor específico por ID.

Archive Meter

Arquive um medidor para parar de rastrear o uso.

Unarchive Meter

Restaure um medidor arquivado para retomar o rastreamento.

​
Criando um Medidor

1

Basic Information

​
string
obrigatório
Um nome descritivo para o medidor (por exemplo, “API Requests”, “Token Usage”).
​
string
obrigatório
O nome exato do evento a ser correspondido (diferencia maiúsculas de minúsculas). Exemplos: api.call, image.generated.
2

Aggregation

​
string
obrigatório
Escolha como os eventos são agregados:
  • Count: Número total de eventos (chamadas de API, uploads)
  • Sum: Soma de valores numéricos (tokens, bytes)
  • Max: Maior valor no período (pico de usuários)
  • Last: Valor mais recente
​
string
A chave de metadata a ser agregada (obrigatória para Sum, Max e Last). Exemplos: tokens, bytes, duration_ms.
​
string
obrigatório
O rótulo da unidade para faturas e relatórios. Exemplos: calls, tokens, GB, hours.
3

Filtering (Optional)

Interface de filtragem de eventos com lógica AND/OR e operadores de comparação
Adicione condições para filtrar quais eventos são contados:
  • Lógica AND: Todas as condições devem corresponder
  • Lógica OR: Qualquer condição pode corresponder
Comparadores disponíveis: igual a, diferente de, maior que, maior ou igual a, menor que, menor ou igual a, contém, não contém.Ative a filtragem, escolha sua lógica e adicione condições com uma chave de propriedade, um comparador e um valor.
4

Create

Revise sua configuração e clique em Create Meter.

​
Visualizando Análises

Dashboard de analytics do medidor mostrando visão geral do uso, eventos e dados dos clientes
O dashboard do seu medidor exibe:
  • Overview: Uso total e tendências de uso ao longo do tempo
  • Events: Eventos individuais recebidos e seus metadados
  • Customers: Totais de uso e cobranças por cliente

​
Cobrança em Créditos em vez de Moeda

Por padrão, os medidores cobram dos clientes por unidade em dólares (ou na moeda configurada). Em vez disso, você pode configurar um medidor para deduzir o uso do saldo de créditos de um cliente, fazendo com que o uso consuma créditos em vez de gerar uma cobrança monetária.
A dedução baseada em créditos exige um Credit Entitlement associado ao mesmo produto. Crie primeiro o credit entitlement e, em seguida, vincule-o ao medidor.

​
Quando usar dedução baseada em créditos

​
Configurando um medidor para deduzir créditos

1

Create a Credit Entitlement

Primeiro, crie um credit entitlement em Products → Credits. Defina a unidade (por exemplo, “API Calls”, “Tokens”), a precisão e as configurações do ciclo de vida (expiração, rollover, excedente).Consulte o guia de Faturamento Baseado em Créditos para obter instruções detalhadas.
2

Create or Edit a Usage-Based Product

Acesse seu produto baseado em uso e abra a seção de configuração do Meter.
3

Add a Meter

Clique no botão + para anexar um medidor. Configure o nome do evento, o tipo de agregação e a unidade de medição como de costume.
4

Enable 'Bill Usage in Credits'

Ative Bill usage in Credits na configuração do medidor para revelar as configurações de créditos:
Configuração de medidor com cobrança de uso em créditos ativada

Toggle 'Bill usage in Credits' to switch from currency-based to credit-based deduction.

​
string
obrigatório
Selecione de qual credit entitlement este medidor fará as deduções.
​
number
obrigatório
O número de unidades de uso necessárias para deduzir 1 crédito. Por exemplo:
  • 1 = cada evento do medidor deduz 1 crédito
  • 100 = 100 eventos do medidor deduzem 1 crédito
  • 1000 = 1.000 chamadas de API consomem 1 crédito
5

Free Threshold and Credits

O Free Threshold se aplica a medidores cobrados em dinheiro, não a medidores cobrados em créditos. Quando um medidor cobra em créditos, cada unidade conta para a dedução de créditos.Exemplo: Com meter-units-per-credit igual a 1, um cliente que faça 2.500 chamadas de API terá 2.500 créditos deduzidos.

​
Como a dedução de créditos funciona

Uma vez configurado, o pipeline de dedução é executado automaticamente:
  1. Eventos chegam — Seu aplicativo envia eventos de uso por meio da Event Ingestion API.
  2. O medidor agrega — Os eventos são agregados de acordo com a configuração do seu medidor (Count, Sum, Max, Last).
  3. O worker em segundo plano processa — A cada minuto, um worker busca novos eventos desde o último checkpoint.
  4. Os créditos são deduzidos — O uso agregado é convertido em créditos usando a taxa meter_units_per_credit e deduzido usando a ordenação FIFO (as concessões que expiram primeiro são consumidas primeiro).
  5. O excedente é rastreado — Se o saldo chegar a zero, o uso adicional será registrado como excedente e tratado de acordo com o comportamento configurado (perdoado na redefinição, cobrado na próxima fatura ou transferido como déficit). Dodo Payments não bloqueia o uso quando o saldo se esgota. Para interromper o acesso quando o saldo chegar a zero, verifique o saldo no seu aplicativo.
A dedução de créditos é executada de forma assíncrona (aproximadamente a cada 1 minuto). Pode haver um breve atraso entre a ingestão do evento e a dedução do saldo. Projete seu aplicativo para lidar com esse atraso e não dependa de verificações de saldo em tempo real para controlar o acesso em solicitações individuais.

​
Vários medidores, um pool de créditos

Você pode vincular vários medidores no mesmo produto ao mesmo credit entitlement. Todos os medidores fazem deduções de um saldo compartilhado. Exemplo: uma plataforma de IA com dois medidores:
  • text.generation — 1 crédito por 1.000 tokens
  • image.generation — 10 créditos por imagem
Ambos deduzem do mesmo pool “AI Credits”. O cliente vê um único saldo unificado em seu portal.
Use diferentes taxas meter_units_per_credit entre os medidores para expressar custos relativos. Operações caras (geração de imagens) exigem menos unidades de medidor por crédito do que operações baratas (completação de texto).

List Customer Ledger

Veja o histórico completo de dedução de créditos de um cliente.

Get Customer Balance

Verifique o saldo atual de créditos de um cliente via API.

​
Solução de problemas

  • O nome do evento deve corresponder exatamente (diferencia maiúsculas de minúsculas)
  • Verifique se os filtros do medidor não estão excluindo eventos
  • Confirme se os IDs dos clientes existem na sua conta
  • Desative temporariamente os filtros para testar
  • Verifique se Over Property corresponde exatamente à chave de metadata
  • Use números, não strings: tokens: 150, não tokens: "150"
  • Inclua as propriedades obrigatórias em todos os eventos
  • Diferencie maiúsculas de minúsculas exatamente
  • Use os operadores corretos para o tipo de dado
  • Certifique-se de que os eventos incluam as propriedades filtradas
  • Verifique a aba Events para contar os eventos realmente recebidos
  • Confirme o tipo de agregação (Count ou Sum)
  • Certifique-se de que os valores sejam numéricos para Sum e Max

​
Próximos passos

Send Events

Comece a enviar eventos de uso da sua aplicação para os seus medidores.

View Blueprints

Use configurações prontas de medidores para casos de uso comuns.
Última modificação em 26 de setembro de 2026