Usage-Based Billing Integration guide

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:

Configure Basic Information

Set up the fundamental details for your meter.

string

wajib

Choose a clear, descriptive name that identifies what this meter tracks.Examples: “Tokens”, “API Calls”, “Storage Usage”, “Compute Hours”

string

Provide a detailed explanation of what this meter measures.Example: “Counts each POST /v1/orders request made by the customer”

string

wajib

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.

Configure Aggregation Settings

Define how the meter calculates usage from your events.

string

wajib

Select how events should be aggregated:

Count
Sum
Max
Last

Simply counts the number of events received.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

wajib

Define the unit label for display purposes in reports and billing.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

Pilih dari operator yang tersedia:

equals - Pencocokan tepat
not_equals - Filter pengecualian
greater_than - Perbandingan numerik
greater_than_or_equals - Perbandingan numerik (inklusif)
less_than - Perbandingan numerik
less_than_or_equals - Perbandingan numerik (inklusif)
contains - String mengandung substring
does_not_contain - Filter pengecualian string

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

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:

Choose Usage-Based Billing Product Type

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

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.

Add Your Meter

In the meter selection panel:

Click Add Meters to view available meters
Select the meter you created from the dropdown list
The selected meter will appear in your product configuration

Configure Price Per Unit

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

number

wajib

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

Set Free Threshold (Optional)

Configure a free usage allowance before billing begins.

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.

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:

string

wajib

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

string

wajib

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

string

wajib

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

string

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

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

Hal-Hal Penting untuk Ingestion yang Andal

Ikuti praktik berikut agar pelacakan penggunaan tetap akurat dan tangguh di production.

Gunakan event_id yang deterministik dan idempoten. event_id harus unik di seluruh event dan berfungsi sebagai idempotency key — event_id yang digunakan ulang akan dianggap sebagai duplikat dan tidak dihitung lagi, sehingga retry tidak pernah menyebabkan double-billing. Turunkan ID dari tindakan yang dilakukan, bukan dari nilai acak, misalnya `${customer_id}_${action}_${timestamp}`.

Batch event, hingga 1.000 per request. Endpoint /events/ingest memberlakukan batas maksimum 1.000 event per call; batch yang lebih besar akan ditolak, jadi bagi volume tinggi ke dalam beberapa call. Untuk workload bervolume tinggi, buffer event dan flush dalam batch, bukan mengirim satu request per event.

Lakukan retry pada 5xx dan 429, jangan pada 4xx. Lakukan retry pada server error (5xx) dan rate limit (429) dengan exponential backoff. Jangan melakukan retry pada validation error 400/422 — payload tersebut malformed dan akan selalu gagal; perbaiki lalu kirim ulang. Masukkan event yang masih gagal setelah retry ke dalam queue agar tidak ada yang hilang.

Tetapkan timestamp dengan sengaja. Abaikan timestamp untuk event real-time dan nilainya akan default ke waktu ingestion. Tetapkan secara eksplisit (ISO 8601) saat melakukan backfill atau mengirim event yang tertunda/dibatch agar penggunaan masuk ke periode billing yang benar.

Kirim metadata yang diagregasi sebagai angka, bukan string. Setiap properti yang direferensikan oleh Over Property suatu meter (Sum, Max, Last) harus bertipe numerik — { "tokens": 150 }, bukan { "tokens": "150" }. Nilai string tidak akan diagregasi.

Analytics Usage-Based Billing

Pantau dan analisis data usage-based billing Anda dengan dashboard analytics yang komprehensif. Lacak pola konsumsi customer, performa meter, dan tren billing untuk mengoptimalkan strategi harga serta memahami perilaku penggunaan.

Analytics Ikhtisar

Tab Overview menyediakan tampilan komprehensif mengenai performa usage-based billing Anda:

Metrik Aktivitas

Lacak statistik penggunaan utama di berbagai periode waktu:

metric

Menampilkan aktivitas penggunaan untuk periode billing saat ini, sehingga membantu Anda memahami pola konsumsi bulanan.

metric

Menampilkan statistik penggunaan kumulatif sejak Anda mulai melakukan tracking, sehingga memberikan insight pertumbuhan jangka panjang.

Gunakan pemilih periode waktu untuk membandingkan penggunaan antarbulan dan mengidentifikasi tren musiman atau pola pertumbuhan.

Grafik Kuantitas Meter

Grafik kuantitas meter memvisualisasikan tren penggunaan dari waktu ke waktu dengan fitur berikut:

Visualisasi time-series: Lacak pola penggunaan berdasarkan hari, minggu, atau bulan
Dukungan multiple meter: Lihat data dari berbagai meter secara bersamaan
Analisis tren: Identifikasi lonjakan penggunaan, pola, dan lintasan pertumbuhan

Grafik secara otomatis menyesuaikan skala berdasarkan volume penggunaan dan rentang waktu yang dipilih, sehingga memberikan visibilitas yang jelas terhadap fluktuasi kecil maupun perubahan penggunaan yang besar.

Analytics Event

Tabel event yang menampilkan nama event, ID, dan kontrol pagination untuk analisis event secara mendetail

Tab Events menyediakan visibilitas terperinci terhadap setiap event penggunaan:

Tampilan Informasi Event

Tabel event menyediakan tampilan yang jelas mengenai setiap event penggunaan dengan kolom berikut:

Nama Event: Tindakan atau pemicu spesifik yang menghasilkan event penggunaan
ID Event: Identifier unik untuk setiap instance event
ID Customer: Customer yang terkait dengan event
Timestamp: Waktu terjadinya event

Tampilan ini memungkinkan Anda melacak dan memantau setiap event penggunaan di seluruh customer, serta memberikan transparansi terhadap kalkulasi billing dan pola penggunaan.

Analytics Customer

Tab Customers menyediakan tampilan tabel terperinci mengenai data penggunaan customer dengan informasi berikut:

Kolom Data yang Tersedia

string

Alamat email customer untuk identifikasi.

string

Identifier unik untuk subscription customer.

number

Jumlah unit gratis yang termasuk dalam plan customer sebelum biaya berlaku.

currency

Biaya per unit untuk penggunaan yang melampaui batas gratis.

timestamp

Timestamp event penggunaan terbaru customer.

currency

Total jumlah yang dibebankan kepada customer untuk usage-based billing.

number

Total jumlah unit yang telah digunakan customer.

number

Jumlah unit yang melampaui batas gratis dan dikenai biaya.

Fitur Tabel

Filtering Kolom: Gunakan fitur “Edit Columns” untuk menampilkan/menyembunyikan kolom data tertentu
Pembaruan Real-time: Data penggunaan mencerminkan metrik konsumsi terbaru

Contoh Agregasi

Berikut contoh praktis cara kerja berbagai jenis agregasi:

Memahami Jenis Agregasi

Berbagai jenis agregasi digunakan untuk skenario billing yang berbeda. Pilih jenis yang tepat berdasarkan cara Anda ingin mengukur dan membebankan biaya penggunaan.

Contoh Implementasi Praktis

Contoh-contoh ini menunjukkan penerapan setiap jenis agregasi di dunia nyata dengan event sampel dan hasil yang diharapkan.

Count Aggregation - API Calls

Skenario: Lacak jumlah total API requestKonfigurasi Meter:

Nama Event: api.call
Jenis Agregasi: Count
Unit Pengukuran: calls

Event Sampel:

{
  "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"}
  ]
}

Hasil: 3 call dibebankan kepada customer

Sum Aggregation - Data Transfer

Skenario: Hitung biaya berdasarkan total byte yang ditransferKonfigurasi Meter:

Nama Event: data.transfer
Jenis Agregasi: Sum
Over Property: bytes
Unit Pengukuran: GB

Event Sampel:

{
  "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}
    }
  ]
}

Hasil: total transfer 1,5 GB dibebankan kepada customer

Max Aggregation - Peak Concurrent Users

Skenario: Hitung biaya berdasarkan jumlah user konkuren tertinggiKonfigurasi Meter:

Nama Event: concurrent.users
Jenis Agregasi: Max
Over Property: count
Unit Pengukuran: users

Event Sampel:

{
  "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}
    }
  ]
}

Hasil: 23 user konkuren pada puncak penggunaan dibebankan kepada customer

Contoh Filtering Event

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

Hanya hitung API call ke endpoint tertentu:Konfigurasi Filter:

Properti: endpoint
Comparator: equals
Nilai: /v1/orders

Event Sampel:

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

Hasil: Event yang memenuhi kriteria filter akan dihitung. Event dengan endpoint berbeda akan diabaikan.

Hanya hitung upload file berukuran besar:Konfigurasi Filter:

Properti: file_size
Comparator: greater_than
Nilai: 1048576 (1 MB dalam byte)

Event Sampel:

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

Hasil: File yang lebih besar dari 1 MB akan dihitung. File yang lebih kecil akan diabaikan.

Hitung API call premium selama jam kerja:Konfigurasi Filter (menggunakan logika AND):

Properti: plan_type, Comparator: equals, Nilai: premium
Properti: hour, Comparator: greater_than_or_equals, Nilai: 9
Properti: hour, Comparator: less_than, Nilai: 17

Event Sampel:

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

Hasil: API call premium selama jam kerja (09.00 - 17.00) akan dihitung.

Pemecahan Masalah

Atasi masalah umum dalam implementasi usage-based billing dan pastikan pelacakan serta billing tetap akurat.

Masalah Umum

Sebagian besar masalah usage-based billing termasuk dalam kategori berikut:

Masalah pengiriman dan pemrosesan event
Masalah konfigurasi meter
Error tipe data dan formatting
Masalah Customer ID dan authentication

Langkah Debugging

Saat melakukan troubleshooting usage-based billing:

Verifikasi pengiriman event di tab analytics Events
Periksa apakah konfigurasi meter sesuai dengan struktur event
Validasi Customer ID dan API authentication
Tinjau kondisi filtering dan pengaturan agregasi

Solusi dan Perbaikan

Events not showing in meter

Penyebab umum:

Nama event tidak sama persis dengan konfigurasi meter
Kondisi filtering event mengecualikan event Anda
Customer ID tidak ada di akun Dodo Payments Anda
Timestamp event berada di luar periode billing saat ini

Solusi:

Verifikasi ejaan nama event dan case sensitivity
Tinjau dan uji kondisi filtering Anda
Pastikan Customer ID valid dan aktif
Periksa apakah timestamp event masih baru dan diformat dengan benar

Aggregation not working as expected

Penyebab umum:

Nama Over Property tidak sesuai dengan key metadata event
Nilai metadata memiliki tipe data yang salah (string vs number)
Properti metadata yang diperlukan tidak ada

Solusi:

Pastikan key metadata sama persis dengan pengaturan Over Property
Konversi angka dalam bentuk string menjadi angka aktual di event Anda
Sertakan semua properti yang diperlukan di setiap event

Filtering not working

Penyebab umum:

Nama properti filter tidak sesuai dengan metadata event
Comparator salah untuk tipe data (string vs number)
Case sensitivity dalam perbandingan string

Solusi:

Periksa kembali apakah nama properti sama persis
Gunakan comparator yang sesuai untuk tipe data Anda
Pertimbangkan case sensitivity saat melakukan filtering string

Referensi API Terkait

Create Meter

Referensi API untuk membuat dan mengonfigurasi usage meter guna melacak konsumsi customer

Ingest Usage Events

Referensi API untuk mengirim usage event ke meter yang telah dikonfigurasi untuk kalkulasi billing

Integration Guides

Billing Deconstructions

Cookbooks

API Reference - Events Ingestion

API Reference - Meters Creation

Creating a Meter

Step-by-Step Meter Creation

Linking Meter in a Product

Product Configuration Process

Sending Usage Events

Event Structure

Usage Events API Examples

Hal-Hal Penting untuk Ingestion yang Andal

Analytics Usage-Based Billing

Analytics Ikhtisar

Metrik Aktivitas

Grafik Kuantitas Meter

Analytics Event

Tampilan Informasi Event

Analytics Customer

Kolom Data yang Tersedia

Fitur Tabel

Contoh Agregasi

Memahami Jenis Agregasi

Contoh Implementasi Praktis

Contoh Filtering Event

Pemecahan Masalah

Masalah Umum

Langkah Debugging

Solusi dan Perbaikan

Referensi API Terkait

Create Meter

Ingest Usage Events

API Reference - Events Ingestion

API Reference - Meters Creation

​Creating a Meter

​Step-by-Step Meter Creation

​Linking Meter in a Product

​Product Configuration Process

​Sending Usage Events

​Event Structure

​Usage Events API Examples

​Hal-Hal Penting untuk Ingestion yang Andal

​Analytics Usage-Based Billing

​Analytics Ikhtisar

​Metrik Aktivitas

​Grafik Kuantitas Meter

​Analytics Event

​Tampilan Informasi Event

​Analytics Customer

​Kolom Data yang Tersedia

​Fitur Tabel

​Contoh Agregasi

​Memahami Jenis Agregasi

​Contoh Implementasi Praktis

​Contoh Filtering Event

​Pemecahan Masalah

​Masalah Umum

​Langkah Debugging

​Solusi dan Perbaikan

​Referensi API Terkait

Create Meter

Ingest Usage Events

Creating a Meter

Step-by-Step Meter Creation

Linking Meter in a Product

Product Configuration Process

Sending Usage Events

Event Structure

Usage Events API Examples

Hal-Hal Penting untuk Ingestion yang Andal

Analytics Usage-Based Billing

Analytics Ikhtisar

Metrik Aktivitas

Grafik Kuantitas Meter

Analytics Event

Tampilan Informasi Event

Analytics Customer

Kolom Data yang Tersedia

Fitur Tabel

Contoh Agregasi

Memahami Jenis Agregasi

Contoh Implementasi Praktis

Contoh Filtering Event

Pemecahan Masalah

Masalah Umum

Langkah Debugging

Solusi dan Perbaikan

Referensi API Terkait