Usage-Based Billing Integration guide

Learn how to set up meters and send usage events to enable accurate usage-based billing with Dodo Payments.

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:

1. Configure Basic Information

   Set up the fundamental details for your meter.

   Meter Name · string · requerido

   Choose a clear, descriptive name that identifies what this meter tracks.

   Examples: “Tokens”, “API Calls”, “Storage Usage”, “Compute Hours”

   Description · string

   Provide a detailed explanation of what this meter measures.

   Example: “Counts each POST /v1/orders request made by the customer”

   Event Name · string · requerido

   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.

2. Configure Aggregation Settings

   Define how the meter calculates usage from your events.

   Aggregation Type · string · requerido

   Select how events should be aggregated:

   Count

   Simply counts the number of events received.

   Use case: API calls, page views, file uploads

   Calculation: Total number of events

   Sum

   Adds up values from a specific property in your events.

   Use case: Data transfer, storage consumption, processing time

   Calculation: Sum of all property values

   Max

   Records the highest value of a specific property during the billing period.

   Use case: Peak concurrent users, maximum storage used, highest bandwidth

   Calculation: Maximum property value observed

   Last

   Uses the most recent value of a specific property.

   Use case: Current plan tier, latest configuration setting

   Calculation: Last recorded property value

   Over Property · string

   The property name from event metadata to aggregate over.

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

   Measurement Unit · string · requerido

   Define the unit label for display purposes in reports and billing.

   Examples: “calls”, “GB”, “hours”, “tokens”

3. 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 Filtering

   Toggle Enable Event Filtering to activate conditional event processing.

   Choose Filter Logic

   Select how multiple conditions are evaluated:

   AND 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"

   OR Logic

   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
4. 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:

1. Choose Usage-Based Billing Product Type

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

2. 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.

3. Add Your Meter

   In the meter selection panel:

   1. Click Add Meters to view available meters
   2. Select the meter you created from the dropdown list
   3. The selected meter will appear in your product configuration
4. Configure Price Per Unit

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

   Price Per Unit · number · requerido

   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
5. Set Free Threshold (Optional)

   Configure a free usage allowance before billing begins.

   Free Threshold · 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.

6. 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:

event_id · string · requerido

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

customer_id · string · requerido

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

event_name · string · requerido

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

timestamp · string

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

metadata · 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:

Node.js

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
        }
      }
    ]
  })
});

​

Aspectos clave para una ingesta fiable

Sigue estas prácticas para mantener el seguimiento del uso preciso y resistente en producción.

Usa event_ids deterministas e idempotentes. El event_id debe ser único en todos los eventos y actúa como clave de idempotencia: un event_id reutilizado se trata como un duplicado y no se vuelve a contabilizar, por lo que los reintentos nunca generan cargos duplicados. Deriva el ID de la acción en lugar de usar un valor aleatorio, por ejemplo, `${customer_id}_${action}_${timestamp}`.

Agrupa los eventos, hasta 1.000 por solicitud. El endpoint /events/ingest impone un máximo estricto de 1.000 eventos por llamada; los lotes que superen ese límite se rechazan, así que divide los volúmenes altos en varias llamadas. Para cargas de trabajo de gran volumen, almacena los eventos en un búfer y envíalos en lotes en lugar de enviar una solicitud por evento.

Reintenta 5xx y 429, nunca 4xx. Reintenta los errores del servidor (5xx) y los límites de tasa (429) con retroceso exponencial. No reintentes los errores de validación 400/422: la carga útil tiene un formato incorrecto y fallará siempre; corrígela y vuelve a enviarla. Pon en cola los eventos que sigan fallando después de los reintentos para que no se pierda ninguno.

Establece las marcas de tiempo de forma intencionada. Omite timestamp para los eventos en tiempo real y se establecerá de forma predeterminada en la hora de ingesta. Establécelo explícitamente (ISO 8601) al recuperar datos históricos o enviar eventos retrasados o agrupados, para que el uso se asigne al periodo de facturación correcto.

Envía los metadatos agregados como números, no como cadenas. Cualquier propiedad a la que haga referencia Over Property (Sum, Max, Last) de un medidor debe ser de tipo numérico: { "tokens": 150 }, no { "tokens": "150" }. Los valores de tipo cadena no se agregarán.

​

Analytics de facturación basada en el uso

Supervisa y analiza tus datos de facturación basada en el uso con un dashboard de analytics completo. Realiza un seguimiento de los patrones de consumo de los clientes, el rendimiento de los medidores y las tendencias de facturación para optimizar tu estrategia de precios y comprender los comportamientos de uso.

​

Analytics general

La pestaña Overview ofrece una vista completa del rendimiento de tu facturación basada en el uso:

​

Métricas de actividad

Realiza un seguimiento de las estadísticas de uso clave en distintos periodos:

Current Month · metric

Muestra la actividad de uso del periodo de facturación actual, lo que te ayuda a comprender los patrones de consumo mensual.

All Time · metric

Muestra las estadísticas de uso acumuladas desde que empezaste a realizar el seguimiento, proporcionando información sobre el crecimiento a largo plazo.

Usa el selector de periodo para comparar el uso entre distintos meses e identificar tendencias estacionales o patrones de crecimiento.

​

Gráfico de cantidades del medidor

El gráfico de cantidades del medidor visualiza las tendencias de uso a lo largo del tiempo e incluye las siguientes funciones:

• Visualización de series temporales: realiza un seguimiento de los patrones de uso por días, semanas o meses
• Compatibilidad con varios medidores: consulta simultáneamente los datos de distintos medidores
• Análisis de tendencias: identifica picos de uso, patrones y trayectorias de crecimiento

El gráfico se escala automáticamente según el volumen de uso y el intervalo de tiempo seleccionado, ofreciendo una visibilidad clara tanto de las pequeñas fluctuaciones como de los cambios importantes en el uso.

​

Analytics de eventos

La pestaña Events ofrece una visibilidad detallada de los eventos de uso individuales:

​

Información mostrada de los eventos

La tabla de eventos ofrece una vista clara de los eventos de uso individuales con las siguientes columnas:

• Nombre del evento: la acción o el desencadenador específico que generó el evento de uso
• ID del evento: identificador único de cada instancia de evento
• ID del cliente: el cliente asociado al evento
• Marca de tiempo: cuándo ocurrió el evento

Esta vista te permite realizar un seguimiento y supervisar eventos de uso individuales en toda tu base de clientes, proporcionando transparencia sobre los cálculos de facturación y los patrones de uso.

​

Analytics de clientes

La pestaña Customers ofrece una vista detallada en forma de tabla de los datos de uso de los clientes con la siguiente información:

​

Columnas de datos disponibles

Customer Email · string

Dirección de email del cliente para su identificación.

Subscription ID · string

Identificador único de la suscripción del cliente.

Free Threshold · number

Número de unidades gratuitas incluidas en el plan del cliente antes de que se apliquen cargos.

Price Per Unit · currency

Coste por unidad del uso que supera el umbral gratuito.

Last Event · timestamp

Marca de tiempo del evento de uso más reciente del cliente.

Total Price · currency

Importe total cobrado al cliente por la facturación basada en el uso.

Consumed Units · number

Número total de unidades consumidas por el cliente.

Chargeable Units · number

Número de unidades que superan el umbral gratuito y por las que se están cobrando cargos.

​

Funciones de la tabla

• Filtrado de columnas: usa la función “Edit Columns” para mostrar u ocultar columnas de datos específicas
• Actualizaciones en tiempo real: los datos de uso reflejan las métricas de consumo más recientes

​

Ejemplos de agregación

Estos son ejemplos prácticos del funcionamiento de los distintos tipos de agregación:

​

Comprender los tipos de agregación

Los distintos tipos de agregación responden a diferentes escenarios de facturación. Elige el tipo adecuado según cómo quieras medir y cobrar el uso.

​

Ejemplos prácticos de implementación

Estos ejemplos muestran aplicaciones reales de cada tipo de agregación, con eventos de muestra y resultados esperados.

Count Aggregation - API Calls

Escenario: realizar un seguimiento del número total de solicitudes de API

Configuración del medidor:

• Nombre del evento: api.call
• Tipo de agregación: Count
• Unidad de medida: calls

Eventos de muestra:

{
  "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: se facturan 3 llamadas al cliente

Sum Aggregation - Data Transfer

Escenario: facturar según el total de bytes transferidos

Configuración del medidor:

• Nombre del evento: data.transfer
• Tipo de agregación: Sum
• Over Property: bytes
• Unidad de medida: GB

Eventos de muestra:

{
  "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: se factura al cliente una transferencia total de 1,5 GB

Max Aggregation - Peak Concurrent Users

Escenario: facturar según el número máximo de usuarios simultáneos

Configuración del medidor:

• Nombre del evento: concurrent.users
• Tipo de agregación: Max
• Over Property: count
• Unidad de medida: users

Eventos de muestra:

{
  "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: se facturan al cliente 23 usuarios simultáneos en el pico máximo

​

Ejemplos de filtrado de eventos

Filter by API Endpoint

Contar únicamente las llamadas de API a endpoints específicos:

Configuración del filtro:

• Propiedad: endpoint
• Comparador: equals
• Valor: /v1/orders

Evento de muestra:

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

Resultado: se contarían los eventos que coincidan con los criterios del filtro. Los eventos con endpoints diferentes se ignorarían.

Filter by Value Range

Contar únicamente las cargas de archivos grandes:

Configuración del filtro:

• Propiedad: file_size
• Comparador: greater_than
• Valor: 1048576 (1 MB en bytes)

Evento de muestra:

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

Resultado: se contarían los archivos de más de 1 MB. Los archivos más pequeños se ignorarían.

Complex Multi-Condition Filters

Contar las llamadas de API premium durante el horario laboral:

Configuración del filtro (mediante lógica AND):

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

Evento de muestra:

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

Resultado: se contarían las llamadas de API premium realizadas durante el horario laboral (de 9:00 a 17:00).

​

Solución de problemas

Resuelve los problemas habituales de la implementación de la facturación basada en el uso y garantiza un seguimiento y una facturación precisos.

​

Problemas habituales

La mayoría de los problemas de facturación basada en el uso pertenecen a estas categorías:

• Problemas de entrega y procesamiento de eventos
• Problemas de configuración de medidores
• Errores de tipo y formato de datos
• Problemas de ID de cliente y autenticación

​

Pasos de depuración

Al solucionar problemas de facturación basada en el uso:

1. Verifica la entrega de eventos en la pestaña de analytics Events
2. Comprueba que la configuración del medidor coincida con la estructura de tus eventos
3. Valida los ID de cliente y la autenticación de API
4. Revisa las condiciones de filtrado y la configuración de agregación

​

Soluciones y correcciones

Events not showing in meter

Causas habituales:

• El nombre del evento no coincide exactamente con la configuración del medidor
• Las condiciones de filtrado de eventos excluyen tus eventos
• El ID de cliente no existe en tu cuenta de Dodo Payments
• La marca de tiempo del evento está fuera del periodo de facturación actual

Soluciones:

• Verifica la ortografía del nombre del evento y la distinción entre mayúsculas y minúsculas
• Revisa y prueba las condiciones de filtrado
• Confirma que el ID de cliente sea válido y esté activo
• Comprueba que las marcas de tiempo de los eventos sean recientes y tengan el formato correcto

Aggregation not working as expected

Causas habituales:

• El nombre de Over Property no coincide con las claves de metadatos del evento
• Los valores de los metadatos tienen un tipo de datos incorrecto (cadena en lugar de número)
• Faltan propiedades de metadatos obligatorias

Soluciones:

• Asegúrate de que las claves de metadatos coincidan exactamente con tu configuración de Over Property
• Convierte los números representados como cadenas en números reales en tus eventos
• Incluye todas las propiedades obligatorias en cada evento

Filtering not working

Causas habituales:

• Los nombres de las propiedades del filtro no coinciden con los metadatos del evento
• El comparador no es adecuado para el tipo de datos (cadena en lugar de número)
• Hay distinción entre mayúsculas y minúsculas en las comparaciones de cadenas

Soluciones:

• Comprueba que los nombres de las propiedades coincidan exactamente
• Usa comparadores adecuados para tus tipos de datos
• Ten en cuenta la distinción entre mayúsculas y minúsculas al filtrar cadenas

​

Referencia de API relacionada

Create Meter

Referencia de API para crear y configurar medidores de uso con los que realizar un seguimiento del consumo de los clientes

Ingest Usage Events

Referencia de API para enviar eventos de uso a tus medidores configurados para realizar cálculos de facturación