Usage-Based Billing Integration guide

API Reference - Events Ingestion

Access the complete API documentation for ingesting usage events and test event ingestion requests and responses interactively.

API Reference - Meters Creation

Explore the full API documentation for creating meters and interactively test meter creation requests and responses.

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

Follow this comprehensive guide to set up your usage meter:

Configure Basic Information

Set up the fundamental details for your meter.

string

obrigatório

Choose a clear, descriptive name that identifies what this meter tracks.Examples: “Tokens”, “API Calls”, “Storage Usage”, “Compute Hours”

string

Provide a detailed explanation of what this meter measures.Example: “Counts each POST /v1/orders request made by the customer”

string

obrigatório

Specify the event identifier that will trigger this meter.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

Simply counts the number of events received.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

Define the unit label for display purposes in reports and billing.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 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

Review your meter configuration and click on Create Meter.

Your meter is now ready to receive and aggregate usage events.

Linking Meter in a Product

Once you have created your meter, you need to link it to a product to enable usage-based billing. This process connects your meter’s usage data to pricing rules for customer billing. Linking meters to products establishes the connection between usage tracking and billing:

Products define pricing rules and billing behavior
Meters provide usage data for billing calculations
Multiple meters can be linked to a single product for complex billing scenarios

Product Configuration Process

Transform your usage data into billable charges by properly configuring your product settings:

Choose Usage-Based Billing Product Type

Navigate to your product creation or editing page and select Usage-Based as the product type.

Select Associated Meter

Click on Associated Meter to open the meter selection panel from the side.This panel allows you to configure which meters will track usage for this product.

Add Your Meter

In the meter selection panel:

Click Add Meters to view available meters
Select the meter you created from the dropdown list
The selected meter will appear in your product configuration

Configure Price Per Unit

Set the pricing for each unit of usage tracked by your meter.

number

obrigatório

Define how much to charge for each unit measured by your meter.Example: Setting $0.50 per unit means:

1,000 units consumed = 1,000 × $0.50 = 500.00 charged
500 units consumed = 500 × $0.50 = 250.00 charged
100 units consumed = 100 × $0.50 = 50.00 charged

Set Free Threshold (Optional)

Configure a free usage allowance before billing begins.

number

Number of units customers can consume at no charge before paid usage calculation starts.How it works:

Free threshold: 100 units
Price per unit: $0.50
Customer usage: 250 units
Calculation: (250 - 100) × $0.50 = **$ 75.00** charged

Free thresholds are ideal for freemium models, trial periods, or providing customers with a base allowance included in their plan.

The free threshold applies to each billing cycle, giving customers fresh allowances monthly or according to your billing schedule.

Save Configuration

Review your meter and pricing configuration, then click Save Changes to finalize the setup.

Your product is now configured for usage-based billing and will automatically charge customers based on their measured consumption.

What happens next:

Usage events sent to your meter will be tracked and aggregated
Billing calculations will apply your pricing rules automatically
Customers will be charged based on actual consumption during each billing cycle

Remember that you can add up to 10 meters per product, enabling sophisticated usage tracking across multiple dimensions like API calls, storage, compute time, and custom metrics.

Sending Usage Events

Once your meter is configured, you can start sending usage events from your application to track customer usage.

Event Structure

Each usage event must include these required fields:

string

obrigatório

Unique identifier for this specific event. Must be unique across all events.

string

obrigatório

The Dodo Payments customer ID this usage should be attributed to.

string

obrigatório

The event name that matches your meter configuration. Event names trigger the appropriate meter.

string

ISO 8601 timestamp when the event occurred. Defaults to current time if not provided.

object

Additional properties for filtering and aggregation. Include any values referenced in your meter’s “Over Property” or filtering conditions.

Usage Events API Examples

Send usage events to your configured meters using the 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 requests
from datetime import datetime

response = requests.post(
    'https://test.dodopayments.com/events/ingest',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    },
    json={
        'events': [
            {
                'event_id': 'api_call_1234',
                'customer_id': 'cus_atXa1lklCRRzMicTqfiw2',
                'event_name': 'api.call',
                'timestamp': datetime.now().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
        }
      }
    ]
  }'

Principais pontos para saber sobre uma ingestão confiável

Siga estas práticas para manter o rastreamento de 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 uma duplicata e não é contabilizado 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 os eventos, até 1.000 por solicitação. O endpoint /events/ingest impõe um limite máximo rígido de 1.000 eventos por chamada; lotes maiores que isso são rejeitados, portanto divida grandes volumes em várias chamadas. Para workloads de alto volume, armazene os eventos em buffer e envie-os em lotes, em vez de enviar uma solicitação por evento.

Tente novamente 5xx e 429, nunca 4xx. Tente novamente em erros do servidor (5xx) e limites de taxa (429), usando backoff 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. Coloque em uma fila os eventos que continuarem falhando após as novas tentativas, para que nenhum seja perdido.

Defina os timestamps intencionalmente. Omita timestamp para eventos em tempo real; ele assumirá como padrão o horário de ingestão. Defina-o explicitamente (ISO 8601) ao fazer backfill ou enviar eventos atrasados/em lote, para que o uso seja registrado no período de cobrança correto.

Envie metadados agregados como números, não como strings. Qualquer propriedade referenciada por Over Property (Sum, Max, Last) de um meter deve ser de tipo numérico — { "tokens": 150 }, 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 abrangente de analytics. Acompanhe os padrões de consumo dos clientes, o desempenho dos meters e as 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 abrangente 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

Exibe 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 rastreamento, 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 do meter

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

Visualização de séries temporais: acompanhe os padrões de uso por dias, semanas ou meses
Suporte a vários meters: visualize dados de diferentes meters 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, proporcionando visibilidade clara tanto de pequenas flutuações quanto de grandes alterações 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 do evento

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: identificador exclusivo de cada instância de 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 nos cálculos de cobrança e nos padrões de uso.

Análises de clientes

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

Colunas de dados disponíveis

string

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

string

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

Custo por unidade para o uso que excede o 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/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

Confira 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 certo com base em como você 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 meter:

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 meter:

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 meter:

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

Conte 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: eventos que corresponderem aos critérios do filtro serão contabilizados. Eventos com endpoints diferentes serão ignorados.

Conte 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 serão contabilizados. Arquivos menores serão ignorados.

Conte 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 (9h às 17h) serão contabilizadas.

Solução de problemas

Resolva problemas comuns na implementação da cobrança baseada em uso e garanta um rastreamento 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 meter
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 analytics Events
Confira se a configuração do meter corresponde à estrutura dos seus 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 meter
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 ortografia 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 string em números reais nos seus 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 em 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 meters de uso para rastrear o consumo dos clientes

Ingest Usage Events

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

Integration Guides

Billing Deconstructions

Cookbooks

API Reference - Events Ingestion

API Reference - Meters Creation

Creating a Meter

Step-by-Step Meter Creation

Linking Meter in a Product

Product Configuration Process

Sending Usage Events

Event Structure

Usage Events API Examples

Principais pontos para saber sobre uma ingestão confiável

Análises de cobrança baseada em uso

Análises gerais

Métricas de atividade

Gráfico de quantidades do meter

Análises de eventos

Exibição de informações do evento

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

​Linking Meter in a Product

​Product Configuration Process

​Sending Usage Events

​Event Structure

​Usage Events API Examples

​Principais pontos para saber sobre uma ingestão confiável

​Análises de cobrança baseada em uso

​Análises gerais

​Métricas de atividade

​Gráfico de quantidades do meter

​Análises de eventos

​Exibição de informações do evento

​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

Linking Meter in a Product

Product Configuration Process

Sending Usage Events

Event Structure

Usage Events API Examples

Principais pontos para saber sobre uma ingestão confiável

Análises de cobrança baseada em uso

Análises gerais

Métricas de atividade

Gráfico de quantidades do meter

Análises de eventos

Exibição de informações do evento

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