उपयोग-आधारित बिलिंग एकीकरण मार्गदर्शिका

API Reference — Events Ingestion

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

API Reference — Meters Creation

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

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 क्या track करता है।उदाहरण: “Tokens”, “API Calls”, “Storage Usage”, “Compute Hours”

string

यह meter क्या मापता है, इसका विस्तृत विवरण।उदाहरण: “ग्राहक द्वारा की गई प्रत्येक 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 — संख्यात्मक तुलना
greater_than_or_equals — संख्यात्मक तुलना (inclusive)
less_than — संख्यात्मक तुलना
less_than_or_equals — संख्यात्मक तुलना (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 से लिंक करना होगा। यह प्रक्रिया आपके meter के usage data को customer billing के लिए pricing rules से जोड़ती है। meters को products से लिंक करने पर usage tracking और billing के बीच कनेक्शन स्थापित होता है:

Products pricing rules और billing behavior परिभाषित करते हैं
Meters billing calculations के लिए usage data प्रदान करते हैं
जटिल billing scenarios के लिए एक product से कई meters लिंक किए जा सकते हैं

Product Configuration Process

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

Choose Usage-Based Billing Product Type

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

Select Associated Meter

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

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 द्वारा मापी गई प्रत्येक 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 शुरू होने से पहले customers द्वारा बिना 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 या customers को उनके plan में शामिल base allowance देने के लिए आदर्श हैं।

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

Save Configuration

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

अब आपका product usage-based billing के लिए configure हो गया है और measured consumption के आधार पर customers से अपने-आप charge करेगा।

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

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

आप प्रत्येक product में 50 तक meters जोड़ सकते हैं, जिससे API calls, storage, compute time और custom metrics जैसे कई dimensions में sophisticated 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 UTC timestamp default होता है। यह 1 घंटे पहले से 5 मिनट भविष्य तक की सीमा में होना चाहिए — इस window से बाहर के timestamps reject कर दिए जाते हैं।

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 os
import requests
from datetime import datetime, timezone

response = requests.post(
    'https://test.dodopayments.com/events/ingest',
    headers={
        'Authorization': f"Bearer {os.environ['DODO_PAYMENTS_API_KEY']}",
        'Content-Type': 'application/json'
    },
    json={
        'events': [
            {
                'event_id': 'api_call_1234',
                'customer_id': 'cus_atXa1lklCRRzMicTqfiw2',
                'event_name': 'api.call',
                'timestamp': datetime.now(timezone.utc).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
        }
      }
    ]
  }'

Reliable Ingestion के लिए महत्वपूर्ण बातें

Production में usage tracking को accurate और 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 प्रति request 1,000 events की hard maximum सीमा लागू करता है। इससे बड़े batches reject कर दिए जाते हैं, इसलिए high volumes को कई calls में बाँटें। High-volume workloads के लिए events को buffer करें और प्रत्येक event के लिए एक request भेजने के बजाय 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 lost न हो।

Timestamps सोच-समझकर सेट करें। Real-time events के लिए timestamp omit करें; यह current UTC timestamp पर default हो जाएगा। Delayed या batched events के लिए इसे स्पष्ट रूप से (ISO 8601) सेट करें, ताकि usage सही billing period में दर्ज हो। Accepted window संकीर्ण है: 1 घंटे से अधिक पुराने या 5 मिनट से अधिक भविष्य के timestamps वाले events reject कर दिए जाते हैं। Historical backfill supported नहीं है — buffered events को एक घंटे के भीतर flush करें।

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 और analyse करें। Customer consumption patterns, meter performance और billing trends को track करके अपनी pricing strategy optimize करें और usage behaviors समझें।

Overview Analytics

Overview tab आपके usage-based billing performance का comprehensive 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: days, weeks या months के across 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

Events table showing event names, IDs, and pagination controls for detailed event analysis

Events tab individual usage events में granular visibility प्रदान करता है:

Event Information Display

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

Event Name: वह specific action या trigger जिसने usage event generate किया
Event ID: प्रत्येक event instance के लिए unique identifier
Customer ID: event से associated 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

पहचान के लिए 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 की गई कुल राशि।

number

customer द्वारा consume की गई कुल units की संख्या।

number

वे units की संख्या जो free threshold से अधिक हैं और जिनके लिए charge किया जा रहा है।

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 की कुल संख्या 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 को total 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 गिनें: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 गिनें:Filter Configuration:

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

Sample Event:

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

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

Business hours के दौरान premium API calls गिनें: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 बजे से शाम 5 बजे तक) के दौरान 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 करें
जाँचें कि meter configuration आपके event structure से match करता है
Customer IDs और API authentication validate करें
Filtering conditions और aggregation settings की समीक्षा करें

Solutions and Fixes

Events not showing in meter

Common causes:

Event name meter configuration से exact 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 की समीक्षा और test करें
Confirm करें कि customer ID valid और active है
जाँचें कि event timestamps recent और properly formatted हैं

Aggregation not working as expected

Common causes:

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

Solutions:

सुनिश्चित करें कि metadata keys आपकी Over Property setting से exact 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 बनाम number)
String comparisons में case sensitivity

Solutions:

दोबारा जाँचें कि property names exact 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।

Integration Guides

Billing Deconstructions

Cookbooks

उपयोग-आधारित बिलिंग एकीकरण मार्गदर्शिका

API Reference — Events Ingestion

API Reference — Meters Creation

Meter बनाना

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

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

Product Configuration Process

Usage Events भेजना

Event Structure

Usage Events API Examples

Reliable 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 Process

​Usage Events भेजना

​Event Structure

​Usage Events API Examples

​Reliable 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 Process

Usage Events भेजना

Event Structure

Usage Events API Examples

Reliable 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