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

obligatorisk

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

obligatorisk

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

obligatorisk

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

obligatorisk

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

Välj från tillgängliga operatorer:

equals - Exakt matchning
not_equals - Exklusionsfilter
greater_than - Numerisk jämförelse
greater_than_or_equals - Numerisk jämförelse (inklusive)
less_than - Numerisk jämförelse
less_than_or_equals - Numerisk jämförelse (inklusive)
contains - Sträng innehåller delsträng
does_not_contain - Sträng exklusionsfilter

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

obligatorisk

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

obligatorisk

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

string

obligatorisk

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

string

obligatorisk

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

Viktigt att känna till för tillförlitlig ingestion

Följ dessa metoder för att hålla användningsspårningen korrekt och motståndskraftig i produktion.

Använd deterministiska, idempotenta event_ids. event_id måste vara unikt för alla händelser och fungerar som idempotency key — ett återanvänt event_id behandlas som en dubblett och räknas inte igen, så retries aldrig leder till dubbeldebitering. Härled ID:t från åtgärden i stället för att använda ett slumpmässigt värde, t.ex. `${customer_id}_${action}_${timestamp}`.

Batcha händelser, upp till 1 000 per request. /events/ingest-endpointen tillämpar ett strikt maximum på 1 000 händelser per anrop; större batchar avvisas, så dela upp stora volymer över flera anrop. För arbetsbelastningar med hög volym bör du buffra händelser och skicka dem i batchar i stället för att skicka ett anrop per händelse.

Försök igen med 5xx och 429, men aldrig med 4xx. Försök igen vid serverfel (5xx) och rate limits (429) med exponentiell backoff. Försök inte igen med valideringsfel för 400/422 — payloaden är felaktigt formaterad och kommer att misslyckas varje gång; korrigera den och skicka den igen. Köa händelser som fortfarande misslyckas efter retries så att inga går förlorade.

Ange timestamps med avsikt. Utelämna timestamp för realtidshändelser, så används ingestion-tiden som standard. Ange det uttryckligen (ISO 8601) vid backfill eller när fördröjda/batchade händelser skickas, så att användningen hamnar i rätt billingperiod.

Skicka aggregerade metadata som tal, inte strängar. Alla properties som refereras av ett mäts Over Property (Sum, Max, Last) måste vara av numerisk typ — { "tokens": 150 }, inte { "tokens": "150" }. Strängvärden aggregeras inte.

Analytics för användningsbaserad debitering

Övervaka och analysera dina data för användningsbaserad debitering med en omfattande analytics-dashboard. Följ kundernas konsumtionsmönster, mätarprestanda och debiteringstrender för att optimera din prisstrategi och förstå användningsbeteenden.

Översiktsanalytics

Fliken Overview ger en omfattande bild av resultatet för din användningsbaserade debitering:

Aktivitetsmått

Följ viktig användningsstatistik över olika tidsperioder:

metric

Visar användningsaktivitet för den aktuella billingperioden, så att du kan förstå månatliga konsumtionsmönster.

metric

Visar kumulativ användningsstatistik sedan du började spåra, vilket ger insikter om långsiktig tillväxt.

Använd väljaren för tidsperiod för att jämföra användning mellan olika månader och identifiera säsongstrender eller tillväxtmönster.

Diagram över mätarkvantiteter

Diagrammet över mätarkvantiteter visualiserar användningstrender över tid med följande funktioner:

Tidsserievisualisering: Följ användningsmönster per dag, vecka eller månad
Stöd för flera mätare: Visa data från olika mätare samtidigt
Trendanalys: Identifiera användningstoppar, mönster och tillväxtbanor

Diagrammet skalas automatiskt baserat på din användningsvolym och valda tidsintervall, vilket ger tydlig insyn i både små variationer och stora förändringar i användningen.

Händelseanalytics

Händelsetabell som visar händelsenamn, ID:n och pagineringskontroller för detaljerad händelseanalys

Fliken Events ger detaljerad insyn i enskilda användningshändelser:

Visning av händelseinformation

Händelsetabellen ger en tydlig bild av enskilda användningshändelser med följande kolumner:

Händelsenamn: Den specifika åtgärd eller trigger som genererade användningshändelsen
Händelse-ID: Unik identifierare för varje händelseinstans
Kund-ID: Kunden som är kopplad till händelsen
Timestamp: När händelsen inträffade

Med den här vyn kan du följa och övervaka enskilda användningshändelser bland dina kunder, vilket ger transparens i debiteringsberäkningar och användningsmönster.

Kundanalytics

Fliken Customers visar en detaljerad tabell över kundernas användningsdata med följande information:

Tillgängliga datakolumner

string

Kundens e-postadress för identifiering.

string

Unik identifierare för kundens subscription.

number

Antalet kostnadsfria enheter som ingår i kundens plan innan debitering börjar.

currency

Kostnaden per enhet för användning över den kostnadsfria gränsen.

timestamp

Timestamp för kundens senaste användningshändelse.

currency

Det totala belopp som debiterats kunden för användningsbaserad debitering.

number

Det totala antalet enheter som kunden har förbrukat.

number

Antalet enheter som överskrider den kostnadsfria gränsen och debiteras.

Tabellfunktioner

Kolumnfiltrering: Använd funktionen “Edit Columns” för att visa eller dölja specifika datakolumner
Realtidsuppdateringar: Användningsdata återspeglar de senaste konsumtionsmåtten

Aggregeringsexempel

Här är praktiska exempel på hur olika aggregeringstyper fungerar:

Förstå aggregeringstyper

Olika aggregeringstyper passar för olika debiteringsscenarier. Välj rätt typ utifrån hur du vill mäta och debitera användning.

Praktiska implementeringsexempel

Dessa exempel visar verkliga tillämpningar av varje aggregeringstyp med exempel på händelser och förväntade resultat.

Count Aggregation - API Calls

Scenario: Följ det totala antalet API-anropMätarkonfiguration:

Händelsenamn: api.call
Aggregeringstyp: Count
Mätningsenhet: calls

Exempel på händelser:

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

Resultat: 3 anrop debiteras kunden

Sum Aggregation - Data Transfer

Scenario: Debitera baserat på totalt överförda byteMätarkonfiguration:

Händelsenamn: data.transfer
Aggregeringstyp: Sum
Over Property: bytes
Mätningsenhet: GB

Exempel på händelser:

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

Resultat: Totalt 1,5 GB överföring debiteras kunden

Max Aggregation - Peak Concurrent Users

Scenario: Debitera baserat på det högsta antalet samtidiga användareMätarkonfiguration:

Händelsenamn: concurrent.users
Aggregeringstyp: Max
Over Property: count
Mätningsenhet: users

Exempel på händelser:

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

Resultat: 23 samtidiga användare vid topp debiteras kunden

Exempel på händelsefiltrering

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

Räkna endast API-anrop till specifika endpoints:Filterkonfiguration:

Property: endpoint
Comparator: equals
Value: /v1/orders

Exempel på händelse:

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

Resultat: Händelser som matchar filterkriterierna räknas. Händelser med andra endpoints ignoreras.

Räkna endast stora filuppladdningar:Filterkonfiguration:

Property: file_size
Comparator: greater_than
Value: 1048576 (1 MB i byte)

Exempel på händelse:

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

Resultat: Filer större än 1 MB räknas. Mindre filer ignoreras.

Räkna premium-API-anrop under kontorstid:Filterkonfiguration (med AND-logik):

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

Exempel på händelse:

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

Resultat: Premium-API-anrop under kontorstid (09.00–17.00) räknas.

Felsökning

Lös vanliga problem med implementeringen av användningsbaserad debitering och säkerställ korrekt spårning och debitering.

Vanliga problem

De flesta problem med användningsbaserad debitering faller inom följande kategorier:

Problem med leverans och bearbetning av händelser
Problem med mätarkonfiguration
Fel i datatyper och formatering
Problem med kund-ID och autentisering

Felsökningssteg

Vid felsökning av användningsbaserad debitering:

Verifiera händelseleveransen på fliken Events i analytics-vyn
Kontrollera att mätarkonfigurationen matchar händelsestrukturen
Validera kund-ID:n och API-autentisering
Granska filtreringsvillkor och aggregeringsinställningar

Lösningar och korrigeringar

Events not showing in meter

Vanliga orsaker:

Händelsenamnet matchar inte mätarkonfigurationen exakt
Händelsefiltreringsvillkor utesluter dina händelser
Kund-ID:t finns inte i ditt Dodo Payments-konto
Händelsens timestamp ligger utanför den aktuella billingperioden

Lösningar:

Kontrollera stavning och skiftläge för händelsenamnet
Granska och testa filtreringsvillkoren
Bekräfta att kund-ID:t är giltigt och aktivt
Kontrollera att händelsetimestamps är aktuella och korrekt formaterade

Aggregation not working as expected

Vanliga orsaker:

Namnet på Over Property matchar inte nycklarna i händelsens metadata
Metadata-värden har fel datatyp (sträng i stället för tal)
Obligatoriska metadata-properties saknas

Lösningar:

Säkerställ att metadata-nycklarna exakt matchar inställningen för Over Property
Konvertera tal som är strängar till faktiska tal i dina händelser
Inkludera alla obligatoriska properties i varje händelse

Filtering not working

Vanliga orsaker:

Filtrets property-namn matchar inte händelsemetadata
Fel comparator för datatypen (sträng i stället för tal)
Skiftlägeskänslighet vid jämförelser av strängar

Lösningar:

Kontrollera noggrant att property-namnen matchar exakt
Använd lämpliga comparators för dina datatyper
Ta hänsyn till skiftlägeskänslighet när du filtrerar strängar

Relaterad API-referens

Create Meter

API-referens för att skapa och konfigurera användningsmätare för spårning av kundkonsumtion

Ingest Usage Events

API-referens för att skicka användningshändelser till dina konfigurerade mätare för debiteringsberäkningar

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

Viktigt att känna till för tillförlitlig ingestion

Analytics för användningsbaserad debitering

Översiktsanalytics

Aktivitetsmått

Diagram över mätarkvantiteter

Händelseanalytics

Visning av händelseinformation

Kundanalytics

Tillgängliga datakolumner

Tabellfunktioner

Aggregeringsexempel

Förstå aggregeringstyper

Praktiska implementeringsexempel

Exempel på händelsefiltrering

Felsökning

Vanliga problem

Felsökningssteg

Lösningar och korrigeringar

Relaterad API-referens

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

​Viktigt att känna till för tillförlitlig ingestion

​Analytics för användningsbaserad debitering

​Översiktsanalytics

​Aktivitetsmått

​Diagram över mätarkvantiteter

​Händelseanalytics

​Visning av händelseinformation

​Kundanalytics

​Tillgängliga datakolumner

​Tabellfunktioner

​Aggregeringsexempel

​Förstå aggregeringstyper

​Praktiska implementeringsexempel

​Exempel på händelsefiltrering

​Felsökning

​Vanliga problem

​Felsökningssteg

​Lösningar och korrigeringar

​Relaterad API-referens

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

Viktigt att känna till för tillförlitlig ingestion

Analytics för användningsbaserad debitering

Översiktsanalytics

Aktivitetsmått

Diagram över mätarkvantiteter

Händelseanalytics

Visning av händelseinformation

Kundanalytics

Tillgängliga datakolumner

Tabellfunktioner

Aggregeringsexempel

Förstå aggregeringstyper

Praktiska implementeringsexempel

Exempel på händelsefiltrering

Felsökning

Vanliga problem

Felsökningssteg

Lösningar och korrigeringar

Relaterad API-referens