> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Usage-Based Billing Integration guide
> Learn how to set up meters and send usage events to enable accurate usage-based billing with Dodo Payments.
Access the complete API documentation for ingesting usage events and test event ingestion requests and responses interactively.
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:
Set up the fundamental details for your meter.
Choose a clear, descriptive name that identifies what this meter tracks.
Examples: "Tokens", "API Calls", "Storage Usage", "Compute Hours"
Provide a detailed explanation of what this meter measures.
Example: "Counts each POST /v1/orders request made by the customer"
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.
Define how the meter calculates usage from your events.
Select how events should be aggregated:
Simply counts the number of events received.
Use case: API calls, page views, file uploads
Calculation: Total number of events
Adds up values from a specific property in your events.
Use case: Data transfer, storage consumption, processing time
Calculation: Sum of all property values
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
Uses the most recent value of a specific property.
Use case: Current plan tier, latest configuration setting
Calculation: Last recorded property value
The property name from event metadata to aggregate over.
This field is required when using Sum, Max, or Last aggregation types.
Define the unit label for display purposes in reports and billing.
Examples: "calls", "GB", "hours", "tokens"
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:
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**
Click **Add condition** to create a new filter rule.
Specify the property name from your event metadata.
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` - Cadena contiene subcadena
* `does_not_contain` - Filtro de exclusión de cadena
Set the target value for comparison.
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.
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:
Navigate to your product creation or editing page and select **Usage-Based** as the product type.
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.
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
Set the pricing for each unit of usage tracked by your meter.
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
Configure a free usage allowance before billing begins.
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.
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:
Unique identifier for this specific event. Must be unique across all events.
The Dodo Payments customer ID this usage should be attributed to.
The event name that matches your meter configuration. Event names trigger the appropriate meter.
ISO 8601 timestamp when the event occurred. Defaults to current time if not provided.
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:
```javascript Node.js theme={null}
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
}
}
]
})
});
```
```python Python theme={null}
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 cURL theme={null}
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 el seguimiento del uso preciso y resistente en producción.
**Usa `event_id`s 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:
Muestra la actividad de uso del periodo de facturación actual, lo que te ayuda a comprender los patrones de consumo mensual.
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
Dirección de email del cliente para su identificación.
Identificador único de la suscripción del cliente.
Número de unidades gratuitas incluidas en el plan del cliente antes de que se apliquen cargos.
Coste por unidad del uso que supera el umbral gratuito.
Marca de tiempo del evento de uso más reciente del cliente.
Importe total cobrado al cliente por la facturación basada en el uso.
Número total de unidades consumidas por el cliente.
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.
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**:
```json theme={null}
{
"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
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**:
```json theme={null}
{
"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
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**:
```json theme={null}
{
"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
Contar únicamente las llamadas de API a endpoints específicos:
Configuración del filtro:
* Propiedad: `endpoint`
* Comparador: `equals`
* Valor: `/v1/orders`
Evento de muestra:
```json theme={null}
{
"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.
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:
```json theme={null}
{
"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.
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:
```json theme={null}
{
"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
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
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
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
Referencia de API para crear y configurar medidores de uso con los que realizar un seguimiento del consumo de los clientes
Referencia de API para enviar eventos de uso a tus medidores configurados para realizar cálculos de facturación