Usage-Based Billing integration guide

API Reference - Events Ingestion

Usage events ingest करने के लिए पूरी API documentation एक्सेस करें और event ingestion requests तथा responses को इंटरैक्टिव रूप से टेस्ट करें।

API Reference - Meters Creation

Meters बनाने के लिए पूरी API documentation देखें और meter creation requests तथा responses को इंटरैक्टिव रूप से टेस्ट करें।

Meter बनाना

Meters यह निर्धारित करते हैं कि billing के लिए आपके usage events को कैसे aggregate और measure किया जाता है। Meter बनाने से पहले अपनी usage tracking strategy की योजना बनाएं:

तय करें कि आप किन usage events को ट्रैक करना चाहते हैं
निर्धारित करें कि events को कैसे aggregate किया जाना चाहिए (count, sum आदि)
विशिष्ट use cases के लिए आवश्यक filtering तय करें

Meter बनाने की चरण-दर-चरण प्रक्रिया

अपना usage meter सेट अप करने के लिए इस विस्तृत गाइड का पालन करें:

Configure Basic Information

अपने meter की मूलभूत जानकारी सेट अप करें।

string

आवश्यक

ऐसा स्पष्ट और वर्णनात्मक नाम चुनें जिससे पता चले कि यह meter क्या ट्रैक करता है।उदाहरण: “Tokens”, “API Calls”, “Storage Usage”, “Compute Hours”

string

यह meter क्या measure करता है, इसका विस्तृत विवरण दें।उदाहरण: “ग्राहक द्वारा की गई प्रत्येक POST /v1/orders request को गिनता है”

string

आवश्यक

वह event identifier निर्दिष्ट करें जो इस meter को trigger करेगा।उदाहरण: “token”, “api.call”, “storage.usage”, “compute.session”

Event name आपके usage events में भेजे गए नाम से बिल्कुल मेल खाना चाहिए। Event names case-sensitive होते हैं।

Configure Aggregation Settings

निर्धारित करें कि meter आपके events से usage की गणना कैसे करेगा।

string

आवश्यक

चुनें कि events को कैसे aggregate किया जाना चाहिए:

Count
Sum
Max
Last

प्राप्त events की संख्या को सरलता से गिनता है।Use case: API calls, page views, file uploadsCalculation: events की कुल संख्या

string

Event metadata से वह property name जिस पर aggregation की जाएगी।

Sum, Max या Last aggregation types का उपयोग करते समय यह field आवश्यक है।

string

आवश्यक

Reports और billing में display के लिए unit label निर्धारित करें।उदाहरण: “calls”, “GB”, “hours”, “tokens”

Configure Event Filtering (Optional)

यह नियंत्रित करने के लिए criteria सेट अप करें कि meter में कौन से events शामिल किए जाएं।

Event filtering से आप ऐसे उन्नत rules बना सकते हैं जो तय करते हैं कि आपके usage calculations में कौन से events योगदान देंगे। यह test events को हटाने, user tiers के आधार पर filtering करने या विशिष्ट actions पर ध्यान केंद्रित करने के लिए उपयोगी है।

Enable Event FilteringConditional event processing सक्रिय करने के लिए Enable Event Filtering को toggle करें।Filter Logic चुनेंचुनें कि multiple conditions का मूल्यांकन कैसे किया जाएगा:

AND Logic
OR Logic

किसी event को count करने के लिए सभी conditions true होनी चाहिए। इसका उपयोग तब करें जब events को एक साथ कई सख्त criteria पूरे करने हों।उदाहरण: उन API calls को गिनें जहां user_tier = "premium" AND endpoint = "/api/v2/users"

किसी event को count करने के लिए कम से कम एक condition true होनी चाहिए। इसका उपयोग तब करें जब आप कई criteria में से किसी एक को पूरा करने वाले events शामिल करना चाहते हों।उदाहरण: उन events को गिनें जहां method = "POST" OR method = "PUT" OR method = "DELETE"

Filter Conditions सेट अप करना

Add Condition

नया filter rule बनाने के लिए Add condition पर क्लिक करें।

Configure Property Key

अपने event metadata से property name निर्दिष्ट करें।

Select Comparator

उपलब्ध operators में से चुनें:

equals - सटीक मिलान
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 में substring शामिल है
does_not_contain - String exclusion filter

Set Comparison Value

Comparison के लिए target value सेट करें।

Add Groups

Complex logic के लिए अतिरिक्त condition groups बनाने हेतु Add Group का उपयोग करें।

Conditions के ठीक से काम करने के लिए filtered properties आपके event metadata में शामिल होनी चाहिए। आवश्यक properties के बिना events को counting से बाहर रखा जाएगा।

Create Meter

अपने meter configuration की समीक्षा करें और Create Meter पर क्लिक करें।

आपका meter अब usage events प्राप्त और aggregate करने के लिए तैयार है।

Product में Meter लिंक करना

Meter बनाने के बाद Usage-Based Billing सक्षम करने के लिए उसे किसी product से link करना आवश्यक है। यह प्रक्रिया आपके meter के usage data को customer billing के लिए pricing rules से जोड़ती है। Meters को products से link करने पर usage tracking और billing के बीच connection स्थापित होता है:

Products pricing rules और billing behavior निर्धारित करते हैं
Meters billing calculations के लिए usage data प्रदान करते हैं
Complex billing scenarios के लिए एक product से multiple meters link किए जा सकते हैं

Product Configuration प्रक्रिया

अपने product settings को सही तरीके से configure करके usage data को billable charges में बदलें:

Choose Usage-Based Billing Product Type

अपने product creation या editing page पर जाएं और product type के रूप में Usage-Based चुनें।

Select Associated Meter

Side panel से meter selection panel खोलने के लिए Associated Meter पर क्लिक करें।यह panel आपको configure करने देता है कि इस product के लिए usage को कौन से meters track करेंगे।

Add Your Meter

Meter selection panel में:

उपलब्ध meters देखने के लिए Add Meters पर क्लिक करें
Dropdown list से आपके द्वारा बनाया गया meter चुनें
चुना गया meter आपके product configuration में दिखाई देगा

Configure Price Per Unit

अपने meter द्वारा track की गई usage की प्रत्येक unit के लिए pricing सेट करें।

number

आवश्यक

अपने meter द्वारा measure की गई प्रत्येक unit के लिए charge निर्धारित करें।उदाहरण: प्रति unit $0.50 सेट करने का अर्थ है:

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)

Billing शुरू होने से पहले free usage allowance configure करें।

number

Paid usage calculation शुरू होने से पहले customer द्वारा बिना charge consume की जा सकने वाली units की संख्या।यह कैसे काम करता है:

Free threshold: 100 units
Price per unit: $0.50
Customer usage: 250 units
Calculation: (250 - 100) × $0.50 = **$ 75.00** charged

Free thresholds freemium models, trial periods या customer के plan में शामिल base allowance देने के लिए आदर्श हैं।

Free threshold प्रत्येक billing cycle पर लागू होता है, जिससे customers को हर महीने या आपके billing schedule के अनुसार नया allowance मिलता है।

Save Configuration

अपने meter और pricing configuration की समीक्षा करें, फिर setup पूरा करने के लिए Save Changes पर क्लिक करें।

आपका product अब Usage-Based Billing के लिए configure है और measured consumption के आधार पर customers से अपने-आप charge करेगा।

इसके बाद क्या होगा:

आपके meter को भेजे गए usage events track और aggregate किए जाएंगे
Billing calculations आपकी pricing rules को automatically लागू करेंगी
प्रत्येक billing cycle के दौरान actual consumption के आधार पर customers से charge लिया जाएगा

ध्यान रखें कि आप प्रत्येक product में अधिकतम 10 meters जोड़ सकते हैं। इससे API calls, storage, compute time और custom metrics जैसे कई dimensions में उन्नत usage tracking संभव होती है।

Usage Events भेजना

Meter configure होने के बाद customer usage track करने के लिए आप अपने application से usage events भेजना शुरू कर सकते हैं।

Event Structure

प्रत्येक usage event में ये required fields शामिल होने चाहिए:

string

आवश्यक

इस specific event के लिए unique identifier। यह सभी events में unique होना चाहिए।

string

आवश्यक

यह वह Dodo Payments customer ID है जिससे इस usage को attribute किया जाना चाहिए।

string

आवश्यक

वह event name जो आपके meter configuration से match करता है। Event names उपयुक्त meter को trigger करते हैं।

string

Event होने का ISO 8601 timestamp। यदि प्रदान नहीं किया गया हो तो current time default होता है।

object

Filtering और aggregation के लिए additional properties। अपने meter की “Over Property” या filtering conditions में referenced values शामिल करें।

Usage Events API Examples

Events API का उपयोग करके अपने configured meters को usage 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 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
        }
      }
    ]
  }'

विश्वसनीय Ingestion के लिए जानने योग्य मुख्य बातें

Production में usage tracking को सटीक और resilient बनाए रखने के लिए इन practices का पालन करें।

Deterministic, idempotent event_ids का उपयोग करें। event_id सभी events में unique होना चाहिए और idempotency key के रूप में काम करता है — दोबारा उपयोग किए गए event_id को duplicate माना जाता है और दोबारा count नहीं किया जाता, इसलिए retries से double-billing नहीं होती। ID को random value के बजाय action से derive करें, जैसे `${customer_id}_${action}_${timestamp}`।

प्रति request अधिकतम 1,000 events का batch भेजें। /events/ingest endpoint प्रति call अधिकतम 1,000 events की सीमा लागू करता है; इससे बड़े batches reject हो जाते हैं, इसलिए high volumes को multiple calls में विभाजित करें। High-volume workloads के लिए, प्रत्येक event के लिए एक request भेजने के बजाय events को buffer करके batches में flush करें।

5xx और 429 पर retry करें, 4xx पर कभी नहीं। Server errors (5xx) और rate limits (429) पर exponential backoff के साथ retry करें। 400/422 validation errors पर retry न करें — payload malformed है और हर बार fail होगा; इसे ठीक करके फिर से भेजें। Retries के बाद भी fail होने वाले events को queue में रखें ताकि कोई event खो न जाए।

Timestamps को सोच-समझकर set करें। Real-time events के लिए timestamp को omit करें; यह ingestion time पर default हो जाता है। Backfilling या delayed/batched events भेजते समय इसे स्पष्ट रूप से (ISO 8601) set करें, ताकि usage सही billing period में दर्ज हो।

Aggregated metadata को strings के बजाय numbers के रूप में भेजें। Meter के Over Property (Sum, Max, Last) द्वारा referenced कोई भी property numeric type की होनी चाहिए — { "tokens": 150 }, न कि { "tokens": "150" }। String values aggregate नहीं होंगी।

Usage-Based Billing Analytics

Comprehensive analytics dashboard के साथ अपने usage-based billing data को monitor और analyze करें। Pricing strategy को optimize करने और usage behaviors को समझने के लिए customer consumption patterns, meter performance और billing trends track करें।

Overview Analytics

Overview tab आपके usage-based billing performance का व्यापक view प्रदान करता है:

Activity Metrics

अलग-अलग time periods में usage के प्रमुख statistics track करें:

metric

यह current billing period की usage activity दिखाता है और monthly consumption patterns समझने में सहायता करता है।

metric

यह tracking शुरू करने के बाद से cumulative usage statistics दिखाता है और long-term growth insights प्रदान करता है।

अलग-अलग months में usage की तुलना करने और seasonal trends या growth patterns पहचानने के लिए time period selector का उपयोग करें।

Meter Quantities Chart

Meter quantities chart निम्नलिखित features के साथ समय के अनुसार usage trends को visualize करता है:

Time-series visualization: दिनों, weeks या months में usage patterns track करें
Multiple meter support: अलग-अलग meters का data एक साथ देखें
Trend analysis: usage spikes, patterns और growth trajectories पहचानें

Chart आपके usage volume और selected time range के आधार पर अपने-आप scale होता है, जिससे छोटे fluctuations और बड़े usage changes दोनों स्पष्ट रूप से दिखाई देते हैं।

Events Analytics

Detailed event analysis के लिए event names, IDs और pagination controls दिखाने वाली events table

Events tab individual usage events का granular view प्रदान करता है:

Event Information Display

Events table निम्नलिखित columns के साथ individual usage events का स्पष्ट view प्रदान करती है:

Event Name: वह specific action या trigger जिसने usage event generate किया
Event ID: प्रत्येक event instance के लिए unique identifier
Customer ID: event से संबद्ध customer
Timestamp: event कब हुआ

यह view आपको अपने customer base में individual usage events को track और monitor करने देता है, जिससे billing calculations और usage patterns में transparency मिलती है।

Customer Analytics

Customers tab निम्नलिखित information के साथ customer usage data का detailed table view प्रदान करता है:

Available Data Columns

string

Identification के लिए customer का email address।

string

Customer की subscription के लिए unique identifier।

number

Charges लागू होने से पहले customer के plan में शामिल free units की संख्या।

currency

Free threshold से अधिक usage के लिए प्रति unit cost।

timestamp

Customer के सबसे हालिया usage event का timestamp।

currency

Usage-based billing के लिए customer से charge की गई total amount।

number

Customer द्वारा consume किए गए कुल units की संख्या।

number

Free threshold से अधिक और charge किए जा रहे units की संख्या।

Table Features

Column Filtering: Specific data columns दिखाने/छिपाने के लिए “Edit Columns” feature का उपयोग करें
Real-time Updates: Usage data सबसे current consumption metrics को दर्शाता है

Aggregation Examples

विभिन्न aggregation types कैसे काम करते हैं, इसके practical examples यहां दिए गए हैं:

Understanding Aggregation Types

अलग-अलग aggregation types अलग billing scenarios के लिए उपयोगी होते हैं। Usage को कैसे measure और charge करना है, उसके आधार पर सही type चुनें।

Practical Implementation Examples

ये examples sample events और expected results के साथ प्रत्येक aggregation type के real-world applications दिखाते हैं।

Count Aggregation - API Calls

Scenario: API requests की total संख्या track करना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: customer को 3 calls के लिए bill किया गया

Sum Aggregation - Data Transfer

Scenario: Transferred total bytes के आधार पर bill करना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: customer को कुल 1.5 GB transfer के लिए bill किया गया

Max Aggregation - Peak Concurrent Users

Scenario: Highest concurrent user count के आधार पर bill करना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: customer को peak concurrent users की संख्या 23 के लिए bill किया गया

Event Filtering Examples

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

केवल specific endpoints पर किए गए API calls को count करें: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: Filter criteria से match करने वाले events count किए जाएंगे। अलग endpoints वाले events ignore किए जाएंगे।

केवल बड़ी file uploads को count करें:Filter Configuration:

Property: file_size
Comparator: greater_than
Value: 1048576 (bytes में 1MB)

Sample Event:

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

Result: 1MB से बड़ी files count की जाएंगी। छोटी files ignore की जाएंगी।

Business hours के दौरान premium API calls count करें:Filter Configuration (AND logic का उपयोग करके):

Property: plan_type, Comparator: equals, Value: premium
Property: hour, Comparator: greater_than_or_equals, 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: Business hours (9 AM - 5 PM) के दौरान किए गए premium API calls count किए जाएंगे।

Troubleshooting

Usage-based billing implementation की common समस्याओं को हल करें और accurate tracking तथा billing सुनिश्चित करें।

Common Issues

अधिकांश usage-based billing समस्याएं इन categories में आती हैं:

Event delivery और processing issues
Meter configuration problems
Data type और formatting errors
Customer ID और authentication issues

Debugging Steps

Usage-based billing की troubleshooting करते समय:

Events analytics tab में event delivery verify करें
Check करें कि meter configuration आपके event structure से match करती है
Customer IDs और API authentication validate करें
Filtering conditions और aggregation settings review करें

Solutions and Fixes

Events not showing in meter

Common causes:

Event name meter configuration से exactly match नहीं करता
Event filtering conditions आपके events को exclude कर रही हैं
Customer ID आपके Dodo Payments account में मौजूद नहीं है
Event timestamp current billing period से बाहर है

Solutions:

Event name की spelling और case sensitivity verify करें
अपनी filtering conditions review और test करें
Confirm करें कि customer ID valid और active है
Check करें कि event timestamps recent और properly formatted हैं

Aggregation not working as expected

Common causes:

Over Property name event metadata keys से match नहीं करता
Metadata values का data type गलत है (string vs number)
Required metadata properties missing हैं

Solutions:

सुनिश्चित करें कि metadata keys आपकी Over Property setting से exactly match करती हैं
अपने events में string numbers को actual numbers में convert करें
प्रत्येक event में सभी required properties शामिल करें

Filtering not working

Common causes:

Filter property names event metadata से match नहीं करते
Data type के लिए गलत comparator है (string vs number)
String comparisons में case sensitivity

Solutions:

दोबारा जांचें कि property names exactly match करते हैं
अपने data types के लिए appropriate comparators का उपयोग करें
Strings filter करते समय case sensitivity पर ध्यान दें

Create Meter

Customer consumption track करने के लिए usage meters बनाने और configure करने का API reference

Ingest Usage Events

Billing calculations के लिए configured meters को usage events भेजने का API reference

अंतिम संशोधन 31 जुलाई 2026

Integration Guides

Billing Deconstructions

Cookbooks

API Reference - Events Ingestion

API Reference - Meters Creation

Meter बनाना

Meter बनाने की चरण-दर-चरण प्रक्रिया

Product में Meter लिंक करना

Product Configuration प्रक्रिया

Usage Events भेजना

Event Structure

Usage Events API Examples

विश्वसनीय Ingestion के लिए जानने योग्य मुख्य बातें

Usage-Based Billing Analytics

Overview Analytics

Activity Metrics

Meter Quantities Chart

Events Analytics

Event Information Display

Customer Analytics

Available Data Columns

Table Features

Aggregation Examples

Understanding Aggregation Types

Practical Implementation Examples

Event Filtering Examples

Troubleshooting

Common Issues

Debugging Steps

Solutions and Fixes

Create Meter

Ingest Usage Events

API Reference - Events Ingestion

API Reference - Meters Creation

​Meter बनाना

​Meter बनाने की चरण-दर-चरण प्रक्रिया

​Product में Meter लिंक करना

​Product Configuration प्रक्रिया

​Usage Events भेजना

​Event Structure

​Usage Events API Examples

​विश्वसनीय Ingestion के लिए जानने योग्य मुख्य बातें

​Usage-Based Billing Analytics

​Overview Analytics

​Activity Metrics

​Meter Quantities Chart

​Events Analytics

​Event Information Display

​Customer Analytics

​Available Data Columns

​Table Features

​Aggregation Examples

​Understanding Aggregation Types

​Practical Implementation Examples

​Event Filtering Examples

​Troubleshooting

​Common Issues

​Debugging Steps

​Solutions and Fixes

​Related API Reference

Create Meter

Ingest Usage Events

Meter बनाना

Meter बनाने की चरण-दर-चरण प्रक्रिया

Product में Meter लिंक करना

Product Configuration प्रक्रिया

Usage Events भेजना

Event Structure

Usage Events API Examples

विश्वसनीय Ingestion के लिए जानने योग्य मुख्य बातें

Usage-Based Billing Analytics

Overview Analytics

Activity Metrics

Meter Quantities Chart

Events Analytics

Event Information Display

Customer Analytics

Available Data Columns

Table Features

Aggregation Examples

Understanding Aggregation Types

Practical Implementation Examples

Event Filtering Examples

Troubleshooting

Common Issues

Debugging Steps

Solutions and Fixes

Related API Reference