Guía de integración de facturación basada en el uso

API Reference — Events Ingestion

Accede a la documentación completa de la API para ingerir eventos de uso y probar de forma interactiva las solicitudes y respuestas de ingesta de eventos.

API Reference — Meters Creation

Explora la documentación completa de la API para crear medidores y prueba de forma interactiva las solicitudes y respuestas de creación 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

Sigue esta guía para configurar tu medidor de uso:

Configure Basic Information

Set up the fundamental details for your meter.

string

requerido

Un nombre claro y descriptivo que identifica lo que registra este medidor.Examples: “Tokens”, “API Calls”, “Storage Usage”, “Compute Hours”

string

Una explicación detallada de lo que mide este medidor.Example: “Counts each POST /v1/orders request made by the customer”

string

requerido

El identificador del evento que activará 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

requerido

Select how events should be aggregated:

Count
Sum
Max
Last

Cuenta el número de eventos recibidos.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

requerido

La etiqueta de unidad que se mostrará en informes y facturas.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

Elige entre los operadores disponibles:

equals — Coincidencia exacta
not_equals — Filtro de exclusión
greater_than — Comparación numérica
greater_than_or_equals — Comparación numérica (inclusiva)
less_than — Comparación numérica
less_than_or_equals — Comparación numérica (inclusiva)
contains — La cadena contiene la subcadena
does_not_contain — Filtro de exclusión de cadenas

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

Revisa la configuración de tu medidor y haz clic en Create Meter.

Tu medidor ya está listo para recibir y agregar eventos de uso.

Vincular un medidor a un producto

Una vez creado el medidor, debes vincularlo a un producto para activar la facturación basada en el uso. Este proceso conecta los datos de uso del medidor con las reglas de precios para la facturación de los clientes. Vincular medidores a productos establece la conexión entre el seguimiento del uso y la facturación:

Los productos definen las reglas de precios y el comportamiento de facturación
Los medidores proporcionan datos de uso para los cálculos de facturación
Se pueden vincular varios medidores a un solo producto para escenarios de facturación complejos

Proceso de configuración del producto

Convierte tus datos de uso en cargos facturables configurando correctamente los ajustes de tu producto:

Choose Usage-Based Billing Product Type

Dirígete a la página de creación o edición de productos y selecciona Usage Based Billing como tipo de precio.

Select Associated Meter

Haz clic en Associated Meters para abrir el panel de selección de medidores.Este panel te permite configurar qué medidores registrarán el uso de este producto.

Add Your Meter

En el panel de selección de medidores:

Haz clic en Add Meters para ver los medidores disponibles
Selecciona en la lista desplegable el medidor que creaste
El medidor seleccionado aparecerá en la configuración de tu producto

Configure Price Per Unit

Establece el precio de cada unidad de uso registrada por tu medidor.

number

requerido

Define cuánto cobrar por cada unidad medida por tu medidor.Ejemplo: Establecer $0.50 por unidad 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)

Configura una asignación de uso gratuita antes de que comience la facturación.

number

Número de unidades que los clientes pueden consumir sin cargo antes de que comience el cálculo del uso de pago.Cómo funciona:

Umbral gratuito: 100 unidades
Precio por unidad: $0.50
Uso del cliente: 250 unidades
Cálculo: (250 - 100) × $0.50 = $75.00 cobrados

Los umbrales gratuitos son ideales para modelos freemium, períodos de prueba o para proporcionar a los clientes una asignación base incluida en su plan.

El umbral gratuito se aplica a cada ciclo de facturación, proporcionando a los clientes nuevas asignaciones cada mes o según tu calendario de facturación.

Save Configuration

Revisa la configuración del medidor y los precios, y haz clic en Save Changes para finalizar la configuración.

Tu producto ya está configurado para la facturación basada en el uso y cobrará automáticamente a los clientes según su consumo medido.

Qué sucede a continuación:

Los eventos de uso enviados a tu medidor se registrarán y agregarán
Los cálculos de facturación aplicarán automáticamente tus reglas de precios
Se cobrará a los clientes según el consumo real durante cada ciclo de facturación

Puedes añadir hasta 50 medidores por producto, lo que permite un seguimiento sofisticado del uso en varias dimensiones, como llamadas a la API, almacenamiento, tiempo de cómputo y métricas personalizadas.

Enviar eventos de uso

Una vez configurado el medidor, puedes comenzar a enviar eventos de uso desde tu aplicación para registrar el uso de los clientes.

Estructura de los eventos

Cada evento de uso debe incluir estos campos obligatorios:

string

requerido

Un identificador único para este evento específico. Debe ser único entre todos los eventos.

string

requerido

El ID de cliente de Dodo Payments al que debe atribuirse este uso.

string

requerido

El nombre del evento que coincide con la configuración de tu medidor. Los nombres de eventos activan el medidor correspondiente.

string

Marca de tiempo ISO 8601 de cuando ocurrió el evento. Si no se proporciona, se utiliza la marca de tiempo UTC actual. Debe encontrarse dentro de la última hora y los próximos 5 minutos; las marcas de tiempo fuera de ese intervalo se rechazan.

object

Propiedades adicionales para el filtrado y la agregación. Incluye cualquier valor al que se haga referencia en las condiciones de filtrado o “Over Property” de tu medidor.

Ejemplos de la API de eventos de uso

Envía eventos de uso a tus medidores configurados mediante la API de Events:

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
        }
      }
    ]
  }'

Aspectos clave para una ingesta fiable

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

Usa event_ids deterministas e idempotentes. El event_id debe ser único entre todos los eventos y actúa como clave de idempotencia. Un event_id reutilizado se trata como duplicado y no se vuelve a contabilizar, por lo que los reintentos nunca generan una doble facturación. 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 solicitud. Las agrupaciones 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 temporalmente los eventos y envíalos en agrupaciones en lugar de enviar una solicitud por evento.

Reintenta los errores 5xx y 429, nunca otros 4xx. Reintenta los errores del servidor (5xx) y los límites de frecuencia (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 utilizará la marca de tiempo UTC actual. Establécelo explícitamente (ISO 8601) para eventos retrasados o agrupados, de modo que el uso se registre en el período de facturación correcto. Ten en cuenta que el intervalo aceptado es reducido: los eventos con una marca de tiempo de hace más de 1 hora o de más de 5 minutos en el futuro se rechazan. No se admite la carga histórica; envía los eventos almacenados en búfer dentro de la hora.

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

Análisis de facturación basada en el uso

Supervisa y analiza tus datos de facturación basada en el uso con un completo panel de análisis. Registra 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.

Análisis general

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

Métricas de actividad

Registra estadísticas clave de uso en distintos períodos:

metric

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

metric

Muestra las estadísticas de uso acumuladas desde que comenzaste el seguimiento y proporciona información sobre el crecimiento a largo plazo.

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

Gráfico de cantidades de los medidores

Gráfico de cantidades de medidores que muestra las tendencias de uso a lo largo del tiempo con una visualización de degradado morado

El gráfico de cantidades de los medidores visualiza las tendencias de uso a lo largo del tiempo con las siguientes funciones:

Visualización de series temporales: registra los patrones de uso diarios, semanales o mensuales
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 ajusta automáticamente según tu volumen de uso y el intervalo de tiempo seleccionado, proporcionando una visibilidad clara tanto de pequeñas fluctuaciones como de cambios importantes en el uso.

Análisis de eventos

Tabla de eventos que muestra nombres de eventos, ID y controles de paginación para un análisis detallado de eventos

La pestaña Events proporciona una visibilidad detallada de cada evento de uso:

Visualización de la información de eventos

La tabla de eventos proporciona una vista clara de cada evento de uso con las siguientes columnas:

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

Esta vista te permite realizar el 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.

Análisis de clientes

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

Columnas de datos disponibles

string

La dirección de correo electrónico del cliente para su identificación.

string

Un identificador único de la suscripción del cliente.

number

Número de unidades gratuitas incluidas en el plan del cliente antes de aplicar cargos.

currency

El costo por unidad del uso que supera el umbral gratuito.

timestamp

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

currency

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

number

Número total de unidades consumidas por el cliente.

number

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

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 de cómo funcionan los distintos tipos de agregación:

Comprender los tipos de agregación

Los distintos tipos de agregación sirven para 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: registrar el número total de solicitudes de APIConfiguració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 transferidosConfiguració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áneosConfiguració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

Ejemplos de filtrado de eventos

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

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 cuentan los eventos que coinciden con los criterios del filtro. Los eventos con endpoints diferentes se ignoran.

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 cuentan los archivos de más de 1 MB. Los archivos más pequeños se ignoran.

Contar las llamadas de API premium durante el horario laboral:Configuración del filtro (usando 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 cuentan las llamadas de API premium realizadas durante el horario laboral (de 9:00 a 17:00).

Solución de problemas

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

Problemas comunes

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:

Verifica la entrega de eventos en la pestaña de análisis Events
Comprueba que la configuración del medidor coincida con la estructura de tus eventos
Valida los ID de cliente y la autenticación de la API
Revisa las condiciones de filtrado y la configuración de agregación

Soluciones y correcciones

Events not showing in meter

Causas comunes:

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 período 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 comunes:

El nombre de Over Property no coincide con las claves de metadatos del evento
Los valores de metadatos tienen el 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 la configuración de Over Property
Convierte los números en cadena en números reales dentro de tus eventos
Incluye todas las propiedades obligatorias en cada evento

Filtering not working

Causas comunes:

Los nombres de las propiedades del filtro no coinciden con los metadatos del evento
Comparador incorrecto para el tipo de datos (cadena en lugar de número)
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 relacionada de la API

Create Meter

Referencia de la API para crear y configurar medidores de uso con los que registrar el consumo de los clientes.

Ingest Usage Events

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

Integration Guides

Billing Deconstructions

Cookbooks

Guía de integración de facturación basada en el uso

API Reference — Events Ingestion

API Reference — Meters Creation

Creating a Meter

Step-by-Step Meter Creation

Vincular un medidor a un producto

Proceso de configuración del producto

Enviar eventos de uso

Estructura de los eventos

Ejemplos de la API de eventos de uso

Aspectos clave para una ingesta fiable

Análisis de facturación basada en el uso

Análisis general

Métricas de actividad

Gráfico de cantidades de los medidores

Análisis de eventos

Visualización de la información de eventos

Análisis de clientes

Columnas de datos disponibles

Funciones de la tabla

Ejemplos de agregación

Comprender los tipos de agregación

Ejemplos prácticos de implementación

Ejemplos de filtrado de eventos

Solución de problemas

Problemas comunes

Pasos de depuración

Soluciones y correcciones

Referencia relacionada de la API

Create Meter

Ingest Usage Events

API Reference — Events Ingestion

API Reference — Meters Creation

​Creating a Meter

​Step-by-Step Meter Creation

​Vincular un medidor a un producto

​Proceso de configuración del producto

​Enviar eventos de uso

​Estructura de los eventos

​Ejemplos de la API de eventos de uso

​Aspectos clave para una ingesta fiable

​Análisis de facturación basada en el uso

​Análisis general

​Métricas de actividad

​Gráfico de cantidades de los medidores

​Análisis de eventos

​Visualización de la información de eventos

​Análisis de clientes

​Columnas de datos disponibles

​Funciones de la tabla

​Ejemplos de agregación

​Comprender los tipos de agregación

​Ejemplos prácticos de implementación

​Ejemplos de filtrado de eventos

​Solución de problemas

​Problemas comunes

​Pasos de depuración

​Soluciones y correcciones

​Referencia relacionada de la API

Create Meter

Ingest Usage Events

Creating a Meter

Step-by-Step Meter Creation

Vincular un medidor a un producto

Proceso de configuración del producto

Enviar eventos de uso

Estructura de los eventos

Ejemplos de la API de eventos de uso

Aspectos clave para una ingesta fiable

Análisis de facturación basada en el uso

Análisis general

Métricas de actividad

Gráfico de cantidades de los medidores

Análisis de eventos

Visualización de la información de eventos

Análisis de clientes

Columnas de datos disponibles

Funciones de la tabla

Ejemplos de agregación

Comprender los tipos de agregación

Ejemplos prácticos de implementación

Ejemplos de filtrado de eventos

Solución de problemas

Problemas comunes

Pasos de depuración

Soluciones y correcciones

Referencia relacionada de la API