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
required
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
required
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
required
Select how events should be aggregated:
Simply counts the number of events received.Use case: API calls, page views, file uploadsCalculation: Total number of events
​
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
required
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 FilteringToggle Enable Event Filtering to activate conditional event processing.Choose Filter LogicSelect 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"
Setting Up Filter Conditions
1

Add Condition

Click Add condition to create a new filter rule.
2

Configure Property Key

Specify the property name from your event metadata.
3

Select Comparator

Choose from available operators:
  • equals - Exact match
  • not equals - Exclusion filter
  • greater than - Numeric comparison
  • greater than or equals - Numeric comparison (inclusive)
  • less than - Numeric comparison
  • less than or equals - Numeric comparison (inclusive)
  • contains - String contains substring
  • does not contain - String exclusion filter
4

Set Comparison Value

Set the target value for comparison.
5

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.
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
required
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=∗∗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
required
Unique identifier for this specific event. Must be unique across all events.
​
customer_id
string
required
The Dodo Payments customer ID this usage should be attributed to.
​
event_name
string
required
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: 
const response = await fetch('https://test.dodopayments.com/events/ingest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DODO_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
        }
      }
    ]
  })
});

​
Usage-Based Billing Analytics

Monitor and analyze your usage-based billing data with comprehensive analytics dashboard. Track customer consumption patterns, meter performance, and billing trends to optimize your pricing strategy and understand usage behaviors.

​
Overview Analytics

The Overview tab provides a comprehensive view of your usage-based billing performance:

​
Activity Metrics

Track key usage statistics across different time periods:
​
Current Month
metric
Shows usage activity for the current billing period, helping you understand monthly consumption patterns.
​
All Time
metric
Displays cumulative usage statistics since you started tracking, providing long-term growth insights.
Use the time period selector to compare usage across different months and identify seasonal trends or growth patterns.

​
Meter Quantities Chart

Meter quantities chart showing usage trends over time with purple gradient visualization
The meter quantities chart visualizes usage trends over time with the following features:
  • Time-series visualization: Track usage patterns across days, weeks, or months
  • Multiple meter support: View data from different meters simultaneously
  • Trend analysis: Identify usage spikes, patterns, and growth trajectories
The chart automatically scales based on your usage volume and selected time range, providing clear visibility into both small fluctuations and major usage changes.

​
Events Analytics

Events table showing event names, IDs, and pagination controls for detailed event analysis
The Events tab provides granular visibility into individual usage events:

​
Event Information Display

The events table provides a clear view of individual usage events with the following columns:
  • Event Name: The specific action or trigger that generated the usage event
  • Event ID: Unique identifier for each event instance
  • Customer ID: The customer associated with the event
  • Timestamp: When the event occurred
This view allows you to track and monitor individual usage events across your customer base, providing transparency into billing calculations and usage patterns.

​
Customer Analytics

The Customers tab provides a detailed table view of customer usage data with the following information:

​
Available Data Columns

​
Customer Email
string
Email address of the customer for identification.
​
Subscription ID
string
Unique identifier for the customer’s subscription.
​
Free Threshold
number
Number of free units included in the customer’s plan before charges apply.
​
Price Per Unit
currency
The cost per unit for usage beyond the free threshold.
​
Last Event
timestamp
Timestamp of the customer’s most recent usage event.
​
Total Price
currency
Total amount charged to the customer for usage-based billing.
​
Consumed Units
number
Total number of units the customer has consumed.
​
Chargeable Units
number
Number of units that exceed the free threshold and are being charged.

​
Table Features

  • Column Filtering: Use the “Edit Columns” feature to show/hide specific data columns
  • Real-time Updates: Usage data reflects the most current consumption metrics

​
Aggregation Examples

Here are practical examples of how different aggregation types work:

​
Understanding Aggregation Types

Different aggregation types serve different billing scenarios. Choose the right type based on how you want to measure and charge for usage.

​
Practical Implementation Examples

These examples demonstrate real-world applications of each aggregation type with sample events and expected results.
Scenario: Track the total number of API requestsMeter Configuration:
  • Event Name: api.call
  • Aggregation Type: Count
  • Measurement Unit: calls
Sample Events:
{
  "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"}
  ]
}
Result: 3 calls billed to customer
Scenario: Bill based on total bytes transferredMeter Configuration:
  • Event Name: data.transfer
  • Aggregation Type: Sum
  • Over Property: bytes
  • Measurement Unit: GB
Sample Events:
{
  "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}
    }
  ]
}
Result: 1.5 GB total transfer billed to customer
Scenario: Bill based on highest concurrent user countMeter Configuration:
  • Event Name: concurrent.users
  • Aggregation Type: Max
  • Over Property: count
  • Measurement Unit: users
Sample Events:
{
  "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}
    }
  ]
}
Result: 23 peak concurrent users billed to customer

​
Event Filtering Examples

Only count API calls to specific endpoints:Filter Configuration:
  • Property: endpoint
  • Comparator: equals
  • Value: /v1/orders
Sample Event:
{
  "event_id": "call_1",
  "customer_id": "cus_123",
  "event_name": "api.call",
  "metadata": {
    "endpoint": "/v1/orders",
    "method": "POST"
  }
}
Result: Events matching the filter criteria would be counted. Events with different endpoints would be ignored.

​
Troubleshooting

Resolve common issues with usage-based billing implementation and ensure accurate tracking and billing.

​
Common Issues

Most usage-based billing problems fall into these categories:
  • Event delivery and processing issues
  • Meter configuration problems
  • Data type and formatting errors
  • Customer ID and authentication issues

​
Debugging Steps

When troubleshooting usage-based billing:
  1. Verify event delivery in the Events analytics tab
  2. Check meter configuration matches your event structure
  3. Validate customer IDs and API authentication
  4. Review filtering conditions and aggregation settings

​
Solutions and Fixes

Common causes:
  • Event name doesn’t exactly match meter configuration
  • Event filtering conditions are excluding your events
  • Customer ID doesn’t exist in your Dodo Payments account
  • Event timestamp is outside the current billing period
Solutions:
  • Verify event name spelling and case sensitivity
  • Review and test your filtering conditions
  • Confirm customer ID is valid and active
  • Check event timestamps are recent and properly formatted
Common causes:
  • Over Property name doesn’t match event metadata keys
  • Metadata values are wrong data type (string vs number)
  • Missing required metadata properties
Solutions:
  • Ensure metadata keys exactly match your Over Property setting
  • Convert string numbers to actual numbers in your events
  • Include all required properties in every event
Common causes:
  • Filter property names don’t match event metadata
  • Wrong comparator for data type (string vs number)
  • Case sensitivity in string comparisons
Solutions:
  • Double-check property names match exactly
  • Use appropriate comparators for your data types
  • Consider case sensitivity when filtering strings