Integrationsguide för användningsbaserad fakturering

API Reference — Events Ingestion

Få tillgång till den fullständiga API-dokumentationen för att ta emot användningshändelser och testa begäranden och svar för händelsemottagning interaktivt.

API Reference — Meters Creation

Utforska den fullständiga API-dokumentationen för att skapa mätare och testa begäranden och svar för skapande av mätare interaktivt.

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

Följ den här guiden för att konfigurera din användningsmätare:

Configure Basic Information

Set up the fundamental details for your meter.

string

obligatorisk

Ett tydligt och beskrivande namn som identifierar vad den här mätaren spårar.Examples: “Tokens”, “API Calls”, “Storage Usage”, “Compute Hours”

string

En detaljerad förklaring av vad mätaren mäter.Example: “Counts each POST /v1/orders request made by the customer”

string

obligatorisk

Händelseidentifieraren som utlöser den här mätaren.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

Räknar antalet mottagna händelser.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

Enhetsetiketten som visas i rapporter och vid fakturering.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 bland tillgängliga operatorer:

equals — Exakt matchning
not_equals — Exkluderingsfilter
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 — Exkluderingsfilter för strängar

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

Granska din mätarkonfiguration och klicka på Create Meter.

Din mätare är nu redo att ta emot och sammanställa användningshändelser.

Länka en mätare till en produkt

När du har skapat din mätare måste du länka den till en produkt för att aktivera förbrukningsbaserad fakturering. Den här processen kopplar mätarens användningsdata till prisregler för kundfakturering. När mätare länkas till produkter upprättas kopplingen mellan användningsspårning och fakturering:

Produkter definierar prisregler och faktureringsbeteende
Mätare tillhandahåller användningsdata för faktureringsberäkningar
Flera mätare kan länkas till en och samma produkt för komplexa faktureringsscenarier

Process för produktkonfiguration

Omvandla dina användningsdata till debiterbara avgifter genom att konfigurera produktinställningarna korrekt:

Choose Usage-Based Billing Product Type

Gå till sidan för att skapa eller redigera produkten och välj Usage Based Billing som pristyp.

Select Associated Meter

Klicka på Associated Meters för att öppna panelen för val av mätare.I den här panelen kan du konfigurera vilka mätare som ska spåra användningen för produkten.

Add Your Meter

I panelen för val av mätare:

Klicka på Add Meters för att visa tillgängliga mätare
Välj mätaren du skapade i rullgardinsmenyn
Den valda mätaren visas i produktkonfigurationen

Configure Price Per Unit

Ange priset för varje användningsenhet som mätaren spårar.

number

obligatorisk

Definiera hur mycket som ska debiteras för varje enhet som mäts av mätaren.Exempel: Om du anger $0.50 per enhet innebär det:

1 000 förbrukade enheter = 1 000 × $0.50 = $500.00 debiterat
500 förbrukade enheter = 500 × $0.50 = $250.00 debiterat
100 förbrukade enheter = 100 × $0.50 = $50.00 debiterat

Set Free Threshold (Optional)

Konfigurera en kostnadsfri användningskvot innan faktureringen börjar.

number

Antalet enheter som kunder kan förbruka utan kostnad innan beräkningen av betald användning börjar.Så fungerar det:

Kostnadsfri gräns: 100 enheter
Pris per enhet: $0.50
Kundens användning: 250 enheter
Beräkning: (250 - 100) × $0.50 = $75.00 debiterat

Kostnadsfria gränser passar bra för freemium-modeller, provperioder eller när du vill ge kunderna en grundläggande kvot som ingår i planen.

Den kostnadsfria gränsen gäller för varje faktureringsperiod och ger kunderna nya kvoter varje månad eller enligt ditt faktureringsschema.

Save Configuration

Granska din mätar- och priskonfiguration och klicka sedan på Save Changes för att slutföra konfigurationen.

Din produkt är nu konfigurerad för förbrukningsbaserad fakturering och debiterar automatiskt kunder baserat på deras uppmätta förbrukning.

Vad händer härnäst:

Användningshändelser som skickas till mätaren spåras och sammanställs
Faktureringsberäkningar tillämpar automatiskt dina prisregler
Kunder debiteras baserat på faktisk förbrukning under varje faktureringsperiod

Du kan lägga till upp till 50 mätare per produkt, vilket möjliggör avancerad användningsspårning över flera dimensioner, till exempel API-anrop, lagring, beräkningstid och anpassade mätvärden.

Skicka användningshändelser

När mätaren är konfigurerad kan du börja skicka användningshändelser från din applikation för att spåra kundernas användning.

Händelsestruktur

Varje användningshändelse måste innehålla följande obligatoriska fält:

string

obligatorisk

En unik identifierare för den specifika händelsen. Måste vara unik för alla händelser.

string

obligatorisk

Dodo Payments-kund-ID:t som användningen ska kopplas till.

string

obligatorisk

Händelsenamnet som matchar din mätarkonfiguration. Händelsenamn utlöser rätt mätare.

string

ISO 8601-tidsstämpel för när händelsen inträffade. Om den inte anges används den aktuella UTC-tidsstämpeln som standard. Måste ligga inom 1 timme bakåt och 5 minuter framåt — tidsstämplar utanför det intervallet avvisas.

object

Ytterligare egenskaper för filtrering och sammanställning. Inkludera alla värden som refereras i mätarens “Over Property” eller filtreringsvillkor.

Exempel på API för användningshändelser

Skicka användningshändelser till dina konfigurerade mätare med 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 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
        }
      }
    ]
  }'

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

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

Använd deterministiska, idempotenta event_id. event_id måste vara unik för alla händelser och fungerar som idempotensnyckel. En återanvänd event_id behandlas som en dubblett och räknas inte igen, så omförsök leder aldrig till dubbelfakturering. Härled ID:t från åtgärden i stället för att använda ett slumpmässigt värde, till exempel `${customer_id}_${action}_${timestamp}`.

Gruppera händelser, upp till 1 000 per begäran. /events/ingest-endpointen har en hård gräns på 1 000 händelser per begäran. Större grupper avvisas, så dela upp stora volymer över flera anrop. För arbetsbelastningar med stora volymer bör du buffra händelser och skicka dem i grupper i stället för att skicka en begäran per händelse.

Gör omförsök för 5xx och 429, aldrig för andra 4xx. Gör omförsök vid serverfel (5xx) och hastighetsbegränsningar (429) med exponentiell backoff. Gör inte omförsök för valideringsfel i 400/422 — payloaden är felaktig och kommer att misslyckas varje gång. Korrigera den och skicka igen. Köa händelser som fortfarande misslyckas efter omförsök så att inga går förlorade.

Ange tidsstämplar medvetet. Utelämna timestamp för händelser i realtid så används den aktuella UTC-tidsstämpeln som standard. Ange den uttryckligen (ISO 8601) för fördröjda eller grupperade händelser så att användningen hamnar i rätt faktureringsperiod. Observera att det accepterade intervallet är snävt: händelser med tidsstämplar mer än 1 timme bakåt eller mer än 5 minuter framåt avvisas. Historisk återinläsning stöds inte — skicka buffrade händelser inom en timme.

Skicka sammanställda metadata som tal, inte strängar. Alla egenskaper som refereras av en mätare i Over Property (Sum, Max, Last) måste vara av numerisk typ — { "tokens": 150 }, inte { "tokens": "150" }. Strängvärden sammanställs inte.

Analys av förbrukningsbaserad fakturering

Övervaka och analysera dina data för förbrukningsbaserad fakturering med en omfattande analyspanel. Spåra kundernas förbrukningsmönster, mätarprestanda och faktureringstrender för att optimera din prisstrategi och förstå användningsbeteenden.

Översiktsanalys

Fliken Overview ger en omfattande bild av resultatet för din förbrukningsbaserade fakturering:

Aktivitetsmått

Spåra viktig användningsstatistik över olika tidsperioder:

metric

Visar användningsaktivitet för den aktuella faktureringsperioden och hjälper dig att förstå månatliga förbrukningsmönster.

metric

Visar kumulativ användningsstatistik sedan du började spåra användningen och 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ätarvärden

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

Tidsserievisualisering: Spåra användningsmönster över dagar, veckor eller månader
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 användningsförändringar.

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:

Event Name: Den specifika åtgärd eller utlösare som genererade användningshändelsen
Event ID: En unik identifierare för varje händelseinstans
Customer ID: Kunden som är kopplad till händelsen
Timestamp: När händelsen inträffade

Den här vyn låter dig spåra och övervaka enskilda användningshändelser bland hela kundbasen och ger insyn i faktureringsberäkningar och användningsmönster.

Kundanalys

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

Tillgängliga datakolumner

string

Kundens e-postadress för identifiering.

string

En unik identifierare för kundens prenumeration.

number

Antalet kostnadsfria enheter som ingår i kundens plan innan debitering tillämpas.

currency

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

timestamp

Tidsstämpeln för kundens senaste användningshändelse.

currency

Det totala belopp som debiterats kunden för förbrukningsbaserad fakturering.

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
Uppdateringar i realtid: Användningsdata återspeglar de senaste förbrukningsmätvärdena

Exempel på sammanställning

Här är praktiska exempel på hur olika sammanställningstyper fungerar:

Förstå sammanställningstyper

Olika sammanställningstyper passar olika faktureringsscenarier. 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 sammanställningstyp med exempel på händelser och förväntade resultat:

Count Aggregation — API Calls

Scenario: Spåra det totala antalet API-begärandenMätarkonfiguration:

Händelsenamn: api.call
Sammanställningstyp: Count
Mätenhet: 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 faktureras kunden

Sum Aggregation — Data Transfer

Scenario: Fakturera baserat på det totala antalet överförda byteMätarkonfiguration:

Händelsenamn: data.transfer
Sammanställningstyp: Sum
Over Property: bytes
Mätenhet: 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: 1,5 GB total överföring faktureras kunden

Max Aggregation — Peak Concurrent Users

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

Händelsenamn: concurrent.users
Sammanställningstyp: Max
Over Property: count
Mätenhet: 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 toppvärdet faktureras 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:

Egenskap: endpoint
Jämförelseoperator: equals
Värde: /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:

Egenskap: file_size
Jämförelseoperator: greater_than
Värde: 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 som är större än 1 MB räknas. Mindre filer ignoreras.

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

Egenskap: plan_type, Jämförelseoperator: equals, Värde: premium
Egenskap: hour, Jämförelseoperator: greater_than_or_equals, Värde: 9
Egenskap: hour, Jämförelseoperator: less_than, Värde: 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 till 17.00) räknas.

Felsökning

Lös vanliga problem med implementering av förbrukningsbaserad fakturering och säkerställ korrekt spårning och fakturering.

Vanliga problem

De flesta problem med förbrukningsbaserad fakturering hör till 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 förbrukningsbaserad fakturering:

Verifiera händelseleveransen på fliken Events i analysvyn
Kontrollera att mätarkonfigurationen överensstämmer med händelsestrukturen
Validera kund-ID:n och API-autentisering
Granska filtreringsvillkor och sammanställningsinställningar

Lösningar och korrigeringar

Events not showing in meter

Vanliga orsaker:

Händelsenamnet överensstämmer inte exakt med mätarkonfigurationen
Händelsefiltreringsvillkor utesluter dina händelser
Kund-ID:t finns inte i ditt Dodo Payments-konto
Händelsens tidsstämpel ligger utanför den aktuella faktureringsperioden

Lösningar:

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

Aggregation not working as expected

Vanliga orsaker:

Namnet på Over Property matchar inte nycklarna i händelsemetadata
Metadatavärdena har fel datatyp (sträng i stället för tal)
Obligatoriska metadataegenskaper saknas

Lösningar:

Se till att metadatanycklarna exakt matchar inställningen för Over Property
Konvertera strängar som innehåller tal till faktiska tal i dina händelser
Inkludera alla obligatoriska egenskaper i varje händelse

Filtering not working

Vanliga orsaker:

Filteregenskapsnamnen matchar inte händelsemetadata
Fel jämförelseoperator för datatypen (sträng i stället för tal)
Skiftlägeskänslighet i strängjämförelser

Lösningar:

Kontrollera noggrant att egenskapsnamnen matchar exakt
Använd lämpliga jämförelseoperatorer 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 att spåra kundernas förbrukning.

Ingest Usage Events

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

Integration Guides

Billing Deconstructions

Cookbooks

Integrationsguide för användningsbaserad fakturering

API Reference — Events Ingestion

API Reference — Meters Creation

Creating a Meter

Step-by-Step Meter Creation

Länka en mätare till en produkt

Process för produktkonfiguration

Skicka användningshändelser

Händelsestruktur

Exempel på API för användningshändelser

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

Analys av förbrukningsbaserad fakturering

Översiktsanalys

Aktivitetsmått

Diagram över mätarvärden

Händelseanalys

Visning av händelseinformation

Kundanalys

Tillgängliga datakolumner

Tabellfunktioner

Exempel på sammanställning

Förstå sammanställningstyper

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

​Länka en mätare till en produkt

​Process för produktkonfiguration

​Skicka användningshändelser

​Händelsestruktur

​Exempel på API för användningshändelser

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

​Analys av förbrukningsbaserad fakturering

​Översiktsanalys

​Aktivitetsmått

​Diagram över mätarvärden

​Händelseanalys

​Visning av händelseinformation

​Kundanalys

​Tillgängliga datakolumner

​Tabellfunktioner

​Exempel på sammanställning

​Förstå sammanställningstyper

​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

Länka en mätare till en produkt

Process för produktkonfiguration

Skicka användningshändelser

Händelsestruktur

Exempel på API för användningshändelser

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

Analys av förbrukningsbaserad fakturering

Översiktsanalys

Aktivitetsmått

Diagram över mätarvärden

Händelseanalys

Visning av händelseinformation

Kundanalys

Tillgängliga datakolumner

Tabellfunktioner

Exempel på sammanställning

Förstå sammanställningstyper

Praktiska implementeringsexempel

Exempel på händelsefiltrering

Felsökning

Vanliga problem

Felsökningssteg

Lösningar och korrigeringar

Relaterad API-referens