Guia de integração de cobrança baseada em uso

API Reference — Events Ingestion

Acesse a documentação completa da API para ingerir eventos de uso e testar interativamente as solicitações e respostas de ingestão de eventos.

API Reference — Meters Creation

Explore a documentação completa da API para criar medidores e teste interativamente as solicitações e respostas de criação de medidores.

Creating a Meter

Meters define how your usage events are aggregated and measured for billing purposes. Before creating a meter, plan your usage tracking strategy:

Identify what usage events you want to track
Determine how events should be aggregated (count, sum, etc.)
Define any filtering requirements for specific use cases

Step-by-Step Meter Creation

Siga este guia para configurar seu medidor de uso:

Configure Basic Information

Set up the fundamental details for your meter.

string

obrigatório

Um nome claro e descritivo que identifique o que este medidor acompanha.Examples: “Tokens”, “API Calls”, “Storage Usage”, “Compute Hours”

string

Uma explicação detalhada do que este medidor mensura.Example: “Counts each POST /v1/orders request made by the customer”

string

obrigatório

O identificador do evento que acionará este medidor.Examples: “token”, “api.call”, “storage.usage”, “compute.session”

The event name must match exactly what you send in your usage events. Event names are case-sensitive.

Configure Aggregation Settings

Define how the meter calculates usage from your events.

string

obrigatório

Select how events should be aggregated:

Count
Sum
Max
Last

Conta o número de eventos recebidos.Use case: API calls, page views, file uploadsCalculation: Total number of events

string

The property name from event metadata to aggregate over.

This field is required when using Sum, Max, or Last aggregation types.

string

obrigatório

O rótulo da unidade para exibição em relatórios e cobranças.Examples: “calls”, “GB”, “hours”, “tokens”

Configure Event Filtering (Optional)

Set up criteria to control which events are included in the meter.

Event filtering allows you to create sophisticated rules that determine which events contribute to your usage calculations. This is useful for excluding test events, filtering by user tiers, or focusing on specific actions.

Enable Event FilteringToggle Enable Event Filtering to activate conditional event processing.Choose Filter LogicSelect how multiple conditions are evaluated:

AND Logic
OR Logic

All conditions must be true for an event to be counted. Use this when you need events to meet multiple strict criteria simultaneously.Example: Count API calls where user_tier = "premium" AND endpoint = "/api/v2/users"

At least one condition must be true for an event to be counted. Use this when you want to include events that meet any of several criteria.Example: Count events where method = "POST" OR method = "PUT" OR method = "DELETE"

Setting Up Filter Conditions

Add Condition

Click Add condition to create a new filter rule.

Configure Property Key

Specify the property name from your event metadata.

Select Comparator

Escolha entre os operadores disponíveis:

equals — Correspondência exata
not_equals — Filtro de exclusão
greater_than — Comparação numérica
greater_than_or_equals — Comparação numérica (inclusiva)
less_than — Comparação numérica
less_than_or_equals — Comparação numérica (inclusiva)
contains — A string contém a substring
does_not_contain — Filtro de exclusão de string

Set Comparison Value

Set the target value for comparison.

Add Groups

Use Add Group to create additional condition groups for complex logic.

Filtered properties must be included in your event metadata for the conditions to work properly. Events missing required properties will be excluded from counting.

Create Meter

Revise a configuração do medidor e clique em Create Meter.

Seu medidor agora está pronto para receber e agregar eventos de uso.

Vinculando um medidor a um produto

Depois de criar seu medidor, você precisa vinculá-lo a um produto para habilitar a cobrança baseada em uso. Esse processo conecta os dados de uso do medidor às regras de preços para a cobrança dos clientes. Vincular medidores a produtos estabelece a conexão entre o acompanhamento de uso e a cobrança:

Os produtos definem as regras de preços e o comportamento da cobrança
Os medidores fornecem dados de uso para os cálculos de cobrança
Vários medidores podem ser vinculados a um único produto para cenários complexos de cobrança

Processo de configuração do produto

Transforme seus dados de uso em cobranças faturáveis configurando corretamente as definições do produto:

Choose Usage-Based Billing Product Type

Acesse a página de criação ou edição do produto e selecione Usage Based Billing como tipo de preço.

Select Associated Meter

Clique em Associated Meters para abrir o painel de seleção de medidores.Esse painel permite configurar quais medidores acompanharão o uso deste produto.

Add Your Meter

No painel de seleção de medidores:

Clique em Add Meters para ver os medidores disponíveis
Selecione na lista suspensa o medidor que você criou
O medidor selecionado aparecerá na configuração do produto

Configure Price Per Unit

Defina o preço de cada unidade de uso acompanhada pelo seu medidor.

number

obrigatório

Defina quanto cobrar por cada unidade medida pelo seu medidor.Exemplo: Definir $0.50 por unidade significa:

1.000 unidades consumidas = 1.000 × $0.50 = $500.00 cobrados
500 unidades consumidas = 500 × $0.50 = $250.00 cobrados
100 unidades consumidas = 100 × $0.50 = $50.00 cobrados

Set Free Threshold (Optional)

Configure uma franquia de uso gratuito antes do início da cobrança.

number

Número de unidades que os clientes podem consumir gratuitamente antes do início do cálculo do uso pago.Como funciona:

Limite gratuito: 100 unidades
Preço por unidade: $0.50
Uso do cliente: 250 unidades
Cálculo: (250 - 100) × $0.50 = $75.00 cobrados

Os limites gratuitos são ideais para modelos freemium, períodos de avaliação ou para oferecer aos clientes uma franquia básica incluída no plano.

O limite gratuito se aplica a cada ciclo de cobrança, oferecendo aos clientes novas franquias mensalmente ou de acordo com sua programação de cobrança.

Save Configuration

Revise o medidor e a configuração de preços e clique em Save Changes para finalizar a configuração.

Seu produto agora está configurado para cobrança baseada em uso e cobrará automaticamente dos clientes com base no consumo medido.

O que acontece em seguida:

Os eventos de uso enviados ao seu medidor serão acompanhados e agregados
Os cálculos de cobrança aplicarão suas regras de preços automaticamente
Os clientes serão cobrados com base no consumo real durante cada ciclo de cobrança

Você pode adicionar até 50 medidores por produto, permitindo um acompanhamento sofisticado do uso em várias dimensões, como chamadas de API, armazenamento, tempo de processamento e métricas personalizadas.

Enviando eventos de uso

Depois que seu medidor estiver configurado, você poderá começar a enviar eventos de uso do seu aplicativo para acompanhar o uso dos clientes.

Estrutura do evento

Cada evento de uso deve incluir estes campos obrigatórios:

string

obrigatório

Um identificador exclusivo para este evento específico. Deve ser exclusivo em todos os eventos.

string

obrigatório

O ID do cliente Dodo Payments ao qual este uso deve ser atribuído.

string

obrigatório

O nome do evento que corresponde à configuração do seu medidor. Os nomes dos eventos acionam o medidor apropriado.

string

Timestamp ISO 8601 de quando o evento ocorreu. Assume o timestamp UTC atual se não for fornecido. Deve estar dentro de 1 hora no passado e 5 minutos no futuro — timestamps fora dessa janela são rejeitados.

object

Propriedades adicionais para filtragem e agregação. Inclua todos os valores referenciados em “Over Property” do seu medidor ou nas condições de filtragem.

Exemplos da API de eventos de uso

Envie eventos de uso aos medidores configurados usando a Events API:

const response = await fetch('https://test.dodopayments.com/events/ingest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    events: [
      {
        event_id: "api_call_1234",
        customer_id: "cus_atXa1lklCRRzMicTqfiw2", 
        event_name: "api.call",
        timestamp: new Date().toISOString(),
        metadata: {
          endpoint: "/v1/orders",
          method: "POST",
          response_size: 1024
        }
      }
    ]
  })
});

import os
import requests
from datetime import datetime, timezone

response = requests.post(
    'https://test.dodopayments.com/events/ingest',
    headers={
        'Authorization': f"Bearer {os.environ['DODO_PAYMENTS_API_KEY']}",
        'Content-Type': 'application/json'
    },
    json={
        'events': [
            {
                'event_id': 'api_call_1234',
                'customer_id': 'cus_atXa1lklCRRzMicTqfiw2',
                'event_name': 'api.call',
                'timestamp': datetime.now(timezone.utc).isoformat(),
                'metadata': {
                    'endpoint': '/v1/orders',
                    'method': 'POST',
                    'response_size': 1024
                }
            }
        ]
    }
)

curl -X POST 'https://test.dodopayments.com/events/ingest' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [
      {
        "event_id": "api_call_1234",
        "customer_id": "cus_atXa1lklCRRzMicTqfiw2",
        "event_name": "api.call", 
        "timestamp": "2024-01-15T10:30:00Z",
        "metadata": {
          "endpoint": "/v1/orders",
          "method": "POST",
          "response_size": 1024
        }
      }
    ]
  }'

Pontos importantes para uma ingestão confiável

Siga estas práticas para manter o acompanhamento do uso preciso e resiliente em produção.

Use event_ids determinísticos e idempotentes. O event_id deve ser exclusivo em todos os eventos e atua como a chave de idempotência. Um event_id reutilizado é tratado como duplicata e não é contado novamente, portanto as novas tentativas nunca geram cobranças duplicadas. Derive o ID da ação em vez de usar um valor aleatório, por exemplo, `${customer_id}_${action}_${timestamp}`.

Agrupe eventos, até 1.000 por solicitação. O endpoint /events/ingest impõe um máximo rígido de 1.000 eventos por solicitação. Lotes maiores são rejeitados; portanto, divida volumes altos em várias chamadas. Para cargas de trabalho de alto volume, armazene os eventos em buffer e envie-os em lotes, em vez de enviar uma solicitação por evento.

Tente novamente em 5xx e 429, nunca em outros 4xx. Tente novamente em erros do servidor (5xx) e limites de taxa (429), usando recuo exponencial. Não tente novamente em erros de validação 400/422 — o payload está malformado e falhará todas as vezes. Corrija-o e reenvie. Enfileire os eventos que continuarem falhando após as tentativas para que nenhum seja perdido.

Defina os timestamps intencionalmente. Omita timestamp para eventos em tempo real; nesse caso, ele assume o timestamp UTC atual. Defina-o explicitamente (ISO 8601) para eventos atrasados ou agrupados, para que o uso seja registrado no período de cobrança correto. Observe que a janela aceita é restrita: eventos com timestamp de mais de 1 hora no passado ou mais de 5 minutos no futuro são rejeitados. O preenchimento histórico não é compatível — envie os eventos armazenados em buffer dentro de uma hora.

Envie metadados agregados como números, não como strings. Qualquer propriedade referenciada por Over Property de um medidor (Sum, Max, Last) deve ser do tipo numérico — { "tokens": 150 }, e não { "tokens": "150" }. Valores de string não serão agregados.

Análises de cobrança baseada em uso

Monitore e analise seus dados de cobrança baseada em uso com um dashboard completo de análises. Acompanhe padrões de consumo dos clientes, desempenho dos medidores e tendências de cobrança para otimizar sua estratégia de preços e entender os comportamentos de uso.

Análises gerais

A aba Overview oferece uma visão completa do desempenho da sua cobrança baseada em uso:

Métricas de atividade

Acompanhe as principais estatísticas de uso em diferentes períodos:

metric

Mostra a atividade de uso do período de cobrança atual, ajudando você a entender os padrões de consumo mensal.

metric

Exibe estatísticas de uso acumuladas desde o início do acompanhamento, oferecendo insights sobre o crescimento de longo prazo.

Use o seletor de período para comparar o uso entre diferentes meses e identificar tendências sazonais ou padrões de crescimento.

Gráfico de quantidades dos medidores

O gráfico de quantidades dos medidores visualiza as tendências de uso ao longo do tempo com os seguintes recursos:

Visualização de série temporal: acompanhe padrões de uso ao longo de dias, semanas ou meses
Suporte a vários medidores: visualize dados de diferentes medidores simultaneamente
Análise de tendências: identifique picos de uso, padrões e trajetórias de crescimento

O gráfico é dimensionado automaticamente com base no volume de uso e no intervalo de tempo selecionado, oferecendo visibilidade clara tanto de pequenas flutuações quanto de grandes mudanças no uso.

Análises de eventos

Tabela de eventos mostrando nomes de eventos, IDs e controles de paginação para análise detalhada de eventos

A aba Events oferece visibilidade detalhada sobre eventos de uso individuais:

Exibição de informações dos eventos

A tabela de eventos oferece uma visão clara dos eventos de uso individuais com as seguintes colunas:

Nome do evento: a ação ou o acionador específico que gerou o evento de uso
ID do evento: um identificador exclusivo para cada instância do evento
ID do cliente: o cliente associado ao evento
Timestamp: quando o evento ocorreu

Essa visualização permite acompanhar e monitorar eventos de uso individuais em toda a sua base de clientes, oferecendo transparência sobre os cálculos de cobrança e os padrões de uso.

Análises de clientes

A aba Customers fornece uma visualização detalhada em tabela dos dados de uso dos clientes com as seguintes informações:

Colunas de dados disponíveis

string

O endereço de e-mail do cliente para identificação.

string

Um identificador exclusivo da assinatura do cliente.

number

Número de unidades gratuitas incluídas no plano do cliente antes da aplicação das cobranças.

currency

O custo por unidade de uso além do limite gratuito.

timestamp

Timestamp do evento de uso mais recente do cliente.

currency

Valor total cobrado do cliente pela cobrança baseada em uso.

number

Número total de unidades consumidas pelo cliente.

number

Número de unidades que excedem o limite gratuito e estão sendo cobradas.

Recursos da tabela

Filtragem de colunas: use o recurso “Edit Columns” para mostrar ou ocultar colunas de dados específicas
Atualizações em tempo real: os dados de uso refletem as métricas de consumo mais atuais

Exemplos de agregação

Veja exemplos práticos de como funcionam diferentes tipos de agregação:

Entendendo os tipos de agregação

Diferentes tipos de agregação atendem a diferentes cenários de cobrança. Escolha o tipo correto com base em como deseja medir e cobrar pelo uso.

Exemplos práticos de implementação

Estes exemplos demonstram aplicações reais de cada tipo de agregação com eventos de exemplo e resultados esperados:

Count Aggregation — API Calls

Cenário: acompanhar o número total de solicitações de APIConfiguração do medidor:

Nome do evento: api.call
Tipo de agregação: Count
Unidade de medida: calls

Eventos de exemplo:

{
  "events": [
    {"event_id": "call_1", "customer_id": "cus_123", "event_name": "api.call"},
    {"event_id": "call_2", "customer_id": "cus_123", "event_name": "api.call"},
    {"event_id": "call_3", "customer_id": "cus_123", "event_name": "api.call"}
  ]
}

Resultado: 3 chamadas cobradas do cliente

Sum Aggregation — Data Transfer

Cenário: cobrar com base no total de bytes transferidosConfiguração do medidor:

Nome do evento: data.transfer
Tipo de agregação: Sum
Over Property: bytes
Unidade de medida: GB

Eventos de exemplo:

{
  "events": [
    {
      "event_id": "transfer_1",
      "customer_id": "cus_123",
      "event_name": "data.transfer",
      "metadata": {"bytes": 1073741824}
    },
    {
      "event_id": "transfer_2",
      "customer_id": "cus_123",
      "event_name": "data.transfer",
      "metadata": {"bytes": 536870912}
    }
  ]
}

Resultado: 1.5 GB de transferência total cobrados do cliente

Max Aggregation — Peak Concurrent Users

Cenário: cobrar com base no maior número de usuários simultâneosConfiguração do medidor:

Nome do evento: concurrent.users
Tipo de agregação: Max
Over Property: count
Unidade de medida: users

Eventos de exemplo:

{
  "events": [
    {
      "event_id": "peak_1",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 15}
    },
    {
      "event_id": "peak_2",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 23}
    },
    {
      "event_id": "peak_3",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 18}
    }
  ]
}

Resultado: 23 usuários simultâneos no pico cobrados do cliente

Exemplos de filtragem de eventos

Filter by API Endpoint
Filter by Value Range
Complex Multi-Condition Filters

Contar apenas chamadas de API para endpoints específicos:Configuração do filtro:

Propriedade: endpoint
Comparador: equals
Valor: /v1/orders

Evento de exemplo:

{
  "event_id": "call_1",
  "customer_id": "cus_123",
  "event_name": "api.call",
  "metadata": {
    "endpoint": "/v1/orders",
    "method": "POST"
  }
}

Resultado: os eventos que correspondem aos critérios do filtro são contados. Eventos com endpoints diferentes são ignorados.

Contar apenas uploads de arquivos grandes:Configuração do filtro:

Propriedade: file_size
Comparador: greater_than
Valor: 1048576 (1 MB em bytes)

Evento de exemplo:

{
  "event_id": "upload_1",
  "customer_id": "cus_123",
  "event_name": "file.upload",
  "metadata": {
    "file_size": 5242880,
    "file_type": "image"
  }
}

Resultado: arquivos maiores que 1 MB são contados. Arquivos menores são ignorados.

Contar chamadas de API premium durante o horário comercial:Configuração do filtro (usando lógica AND):

Propriedade: plan_type, Comparador: equals, Valor: premium
Propriedade: hour, Comparador: greater_than_or_equals, Valor: 9
Propriedade: hour, Comparador: less_than, Valor: 17

Evento de exemplo:

{
  "event_id": "call_1",
  "customer_id": "cus_123",
  "event_name": "api.call",
  "metadata": {
    "plan_type": "premium",
    "hour": 14,
    "endpoint": "/v1/analytics"
  }
}

Resultado: chamadas de API premium durante o horário comercial (das 9h às 17h) são contadas.

Solução de problemas

Resolva problemas comuns na implementação da cobrança baseada em uso e garanta um acompanhamento e uma cobrança precisos.

Problemas comuns

A maioria dos problemas de cobrança baseada em uso se enquadra nestas categorias:

Problemas de entrega e processamento de eventos
Problemas de configuração do medidor
Erros de tipo e formatação de dados
Problemas de ID do cliente e autenticação

Etapas de depuração

Ao solucionar problemas de cobrança baseada em uso:

Verifique a entrega dos eventos na aba de análises Events
Confira se a configuração do medidor corresponde à estrutura dos eventos
Valide os IDs dos clientes e a autenticação da API
Revise as condições de filtragem e as configurações de agregação

Soluções e correções

Events not showing in meter

Causas comuns:

O nome do evento não corresponde exatamente à configuração do medidor
As condições de filtragem de eventos estão excluindo seus eventos
O ID do cliente não existe na sua conta Dodo Payments
O timestamp do evento está fora do período de cobrança atual

Soluções:

Verifique a grafia do nome do evento e a diferenciação entre maiúsculas e minúsculas
Revise e teste suas condições de filtragem
Confirme se o ID do cliente é válido e está ativo
Verifique se os timestamps dos eventos são recentes e estão formatados corretamente

Aggregation not working as expected

Causas comuns:

O nome de Over Property não corresponde às chaves de metadados do evento
Os valores dos metadados têm o tipo de dados incorreto (string em vez de número)
Faltam propriedades de metadados obrigatórias

Soluções:

Garanta que as chaves de metadados correspondam exatamente à configuração de Over Property
Converta números em strings para números reais nos eventos
Inclua todas as propriedades obrigatórias em cada evento

Filtering not working

Causas comuns:

Os nomes das propriedades do filtro não correspondem aos metadados do evento
Comparador incorreto para o tipo de dados (string em vez de número)
Diferenciação entre maiúsculas e minúsculas nas comparações de strings

Soluções:

Verifique novamente se os nomes das propriedades correspondem exatamente
Use comparadores apropriados para seus tipos de dados
Considere a diferenciação entre maiúsculas e minúsculas ao filtrar strings

Referência relacionada da API

Create Meter

Referência da API para criar e configurar medidores de uso para acompanhar o consumo dos clientes.

Ingest Usage Events

Referência da API para enviar eventos de uso aos medidores configurados para cálculos de cobrança.

Integration Guides

Billing Deconstructions

Cookbooks

Guia de integração de cobrança baseada em uso

API Reference — Events Ingestion

API Reference — Meters Creation

Creating a Meter

Step-by-Step Meter Creation

Vinculando um medidor a um produto

Processo de configuração do produto

Enviando eventos de uso

Estrutura do evento

Exemplos da API de eventos de uso

Pontos importantes para uma ingestão confiável

Análises de cobrança baseada em uso

Análises gerais

Métricas de atividade

Gráfico de quantidades dos medidores

Análises de eventos

Exibição de informações dos eventos

Análises de clientes

Colunas de dados disponíveis

Recursos da tabela

Exemplos de agregação

Entendendo os tipos de agregação

Exemplos práticos de implementação

Exemplos de filtragem de eventos

Solução de problemas

Problemas comuns

Etapas de depuração

Soluções e correções

Referência relacionada da API

Create Meter

Ingest Usage Events

API Reference — Events Ingestion

API Reference — Meters Creation

​Creating a Meter

​Step-by-Step Meter Creation

​Vinculando um medidor a um produto

​Processo de configuração do produto

​Enviando eventos de uso

​Estrutura do evento

​Exemplos da API de eventos de uso

​Pontos importantes para uma ingestão confiável

​Análises de cobrança baseada em uso

​Análises gerais

​Métricas de atividade

​Gráfico de quantidades dos medidores

​Análises de eventos

​Exibição de informações dos eventos

​Análises de clientes

​Colunas de dados disponíveis

​Recursos da tabela

​Exemplos de agregação

​Entendendo os tipos de agregação

​Exemplos práticos de implementação

​Exemplos de filtragem de eventos

​Solução de problemas

​Problemas comuns

​Etapas de depuração

​Soluções e correções

​Referência relacionada da API

Create Meter

Ingest Usage Events

Creating a Meter

Step-by-Step Meter Creation

Vinculando um medidor a um produto

Processo de configuração do produto

Enviando eventos de uso

Estrutura do evento

Exemplos da API de eventos de uso

Pontos importantes para uma ingestão confiável

Análises de cobrança baseada em uso

Análises gerais

Métricas de atividade

Gráfico de quantidades dos medidores

Análises de eventos

Exibição de informações dos eventos

Análises de clientes

Colunas de dados disponíveis

Recursos da tabela

Exemplos de agregação

Entendendo os tipos de agregação

Exemplos práticos de implementação

Exemplos de filtragem de eventos

Solução de problemas

Problemas comuns

Etapas de depuração

Soluções e correções

Referência relacionada da API