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

   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 · 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 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 · 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 = **$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:

Node.js

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

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

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.

Count Aggregation - API Calls

Scenario: Track the total number of API requests

Meter 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

Sum Aggregation - Data Transfer

Scenario: Bill based on total bytes transferred

Meter 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

Max Aggregation - Peak Concurrent Users

Scenario: Bill based on highest concurrent user count

Meter 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

Filter by API Endpoint

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.

Filter by Value Range

Only count large file uploads:

Filter Configuration:

• Property: file_size
• Comparator: greater_than
• Value: 1048576 (1MB in bytes)

Sample Event:

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

Result: Files larger than 1MB would be counted. Smaller files would be ignored.

Complex Multi-Condition Filters

Count premium API calls during business hours:

Filter Configuration (using AND logic):

• Property: plan_type, Comparator: equals, Value: premium
• Property: hour, Comparator: greater_than_or_equal, Value: 9
• Property: hour, Comparator: less_than, Value: 17

Sample Event:

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

Result: Premium API calls during business hours (9 AM - 5 PM) would be counted.

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

Events not showing in meter

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

Aggregation not working as expected

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

Filtering not working

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