Integrationsguide för användningsbaserad fakturering

API-referens - Händelseinmatning

Få tillgång till den kompletta API-dokumentationen för att mata in användningsevenemang och testa händelseinmatningsförfrågningar och svar interaktivt.

API-referens - Skapande av mätare

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

Skapa en mätare

Mätare definierar hur dina användningsevenemang aggregeras och mäts för faktureringsändamål. Innan du skapar en mätare, planera din strategi för användningsspårning:

Identifiera vilka användningsevenemang du vill spåra
Bestäm hur händelser ska aggregeras (antal, summa, etc.)
Definiera eventuella filtreringskrav för specifika användningsfall

Steg-för-steg skapande av mätare

Följ denna omfattande guide för att ställa in din användningsmätare:

Konfigurera grundläggande information

Ställ in de grundläggande detaljerna för din mätare.

Mätarnamn

string

obligatorisk

Välj ett tydligt, beskrivande namn som identifierar vad denna mätare spårar.Exempel: “Tokens”, “API-anrop”, “Lagringsanvändning”, “Beräkningstimmar”

Beskrivning

string

Ge en detaljerad förklaring av vad denna mätare mäter.Exempel: “Räknar varje POST /v1/orders-förfrågan som görs av kunden”

Händelsenamn

string

obligatorisk

Specificera händelseidentifieraren som kommer att utlösa denna mätare.Exempel: “token”, “api.call”, “storage.usage”, “compute.session”

Händelsenamnet måste matcha exakt vad du skickar i dina användningsevenemang. Händelsenamn är skiftlägeskänsliga.

Konfigurera aggregeringsinställningar

Definiera hur mätaren beräknar användning från dina händelser.

Aggregeringstyp

string

obligatorisk

Välj hur händelser ska aggregeras:

Antal
Summa
Max
Senaste

Räknar helt enkelt antalet mottagna händelser.Användningsfall: API-anrop, sidvisningar, filuppladdningarBeräkning: Totalt antal händelser

Över egenskap

string

Egenskapsnamnet från händelsemetadata att aggregera över.

Detta fält krävs när du använder aggregeringstyperna Summa, Max eller Senaste.

Mätningsenhet

string

obligatorisk

Definiera enhetsnamnet för visningsändamål i rapporter och fakturering.Exempel: “anrop”, “GB”, “timmar”, “tokens”

Konfigurera händelsefiltrering (valfritt)

Ställ in kriterier för att kontrollera vilka händelser som ingår i mätaren.

Händelsefiltrering gör att du kan skapa sofistikerade regler som avgör vilka händelser som bidrar till dina användningsberäkningar. Detta är användbart för att utesluta testhändelser, filtrera efter användarnivåer eller fokusera på specifika åtgärder.

Aktivera händelsefiltreringVäxla Aktivera händelsefiltrering för att aktivera villkorlig händelsebehandling.Välj filtreringslogikVälj hur flera villkor utvärderas:

OCH-logik
ELLER-logik

Alla villkor måste vara sanna för att en händelse ska räknas. Använd detta när du behöver att händelser ska uppfylla flera strikta kriterier samtidigt.Exempel: Räkna API-anrop där user_tier = "premium" OCH endpoint = "/api/v2/users"

Minst ett villkor måste vara sant för att en händelse ska räknas. Använd detta när du vill inkludera händelser som uppfyller något av flera kriterier.Exempel: Räkna händelser där method = "POST" ELLER method = "PUT" ELLER method = "DELETE"

Ställa in filtreringsvillkor

Lägg till villkor

Klicka på Lägg till villkor för att skapa en ny filtreringsregel.

Konfigurera egenskapsnyckel

Specificera egenskapsnamnet från din händelsemetadata.

Välj jämförare

Välj bland tillgängliga operatörer:

equals - Exakt matchning
not equals - Uteslutningsfilter
greater than - Numerisk jämförelse
greater than or equals - Numerisk jämförelse (inkluderande)
less than - Numerisk jämförelse
less than or equals - Numerisk jämförelse (inkluderande)
contains - Sträng innehåller delsträng
does not contain - Sträng uteslutningsfilter

Ställ in jämförelsevärde

Ställ in målvärdet för jämförelse.

Lägg till grupper

Använd Lägg till grupp för att skapa ytterligare villkorsgrupper för komplex logik.

Filtrerade egenskaper måste ingå i din händelsemetadata för att villkoren ska fungera korrekt. Händelser som saknar nödvändiga egenskaper kommer att uteslutas från räkningen.

Skapa mätare

Granska din mätarkonfiguration och klicka på Skapa mätare.

Din mätare är nu redo att ta emot och aggregera användningsevenemang.

Länka mätare i en produkt

När du har skapat din mätare måste du länka den till en produkt för att möjliggöra användningsbaserad fakturering. Denna process kopplar din mätares användningsdata till prissättningsregler för kundfakturering. Att länka mätare till produkter etablerar kopplingen mellan användningsspårning och fakturering:

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

Produktkonfigurationsprocess

Transformera dina användningsdata till fakturerbara avgifter genom att korrekt konfigurera dina produktinställningar:

Välj produktkategori för användningsbaserad fakturering

Navigera till din produkt skapande eller redigeringssida och välj Användningsbaserad som produkttyp.

Välj associerad mätare

Klicka på Associerad mätare för att öppna mätarvalspanelen från sidan.Denna panel gör att du kan konfigurera vilka mätare som kommer att spåra användning för denna produkt.

Lägg till din mätare

I mätarvalspanelen:

Klicka på Lägg till mätare för att se tillgängliga mätare
Välj den mätare du skapade från rullgardinslistan
Den valda mätaren kommer att visas i din produktkonfiguration

Konfigurera pris per enhet

Ställ in prissättningen för varje enhet av användning som spåras av din mätare.

Pris per enhet

number

obligatorisk

Definiera hur mycket som ska debiteras för varje enhet som mäts av din mätare.Exempel: Att ställa in $0.50 per enhet innebär:

1 000 enheter förbrukade = 1 000 × $0.50 = 500,00 debiterat
500 enheter förbrukade = 500 × $0.50 = 250,00 debiterat
100 enheter förbrukade = 100 × $0.50 = 50,00 debiterat

Ställ in gratis tröskel (valfritt)

Konfigurera en gratis användningsgräns innan faktureringen börjar.

Gratis tröskel

number

Antal enheter kunder kan förbruka utan kostnad innan beräkningen av betald användning börjar.Hur det fungerar:

Gratis tröskel: 100 enheter
Pris per enhet: $0.50
Kundens användning: 250 enheter
Beräkning: (250 - 100) × $0.50 = **$ 75.00** debiterat

Gratiströsklar är idealiska för freemium-modeller, provperioder eller för att ge kunder en grundläggande tilldelning som ingår i deras plan.

Gratiströskeln gäller för varje faktureringscykel, vilket ger kunderna nya tilldelningar varje månad eller enligt din faktureringsschema.

Spara konfiguration

Granska din mätare och prissättningskonfiguration, klicka sedan på Spara ändringar för att slutföra inställningen.

Din produkt är nu konfigurerad för användningsbaserad fakturering och kommer automatiskt att debitera kunder baserat på deras mätta konsumtion.

Vad som händer härnäst:

Användningsevenemang som skickas till din mätare kommer att spåras och aggregeras
Faktureringsberäkningar kommer automatiskt att tillämpa dina prissättningsregler
Kunder kommer att debiteras baserat på faktisk konsumtion under varje faktureringscykel

Kom ihåg att du kan lägga till upp till 10 mätare per produkt, vilket möjliggör sofistikerad användningsspårning över flera dimensioner som API-anrop, lagring, beräkningstid och anpassade mätvärden.

Skicka användningsevenemang

När din mätare är konfigurerad kan du börja skicka användningsevenemang från din applikation för att spåra kundens användning.

Händelsestruktur

Varje användningsevenemang måste inkludera dessa obligatoriska fält:

event_id

string

obligatorisk

Unik identifierare för detta specifika evenemang. Måste vara unik över alla händelser.

customer_id

string

obligatorisk

Dodo Payments kund-ID som denna användning ska tillskrivas.

event_name

string

obligatorisk

Händelsenamnet som matchar din mätarkonfiguration. Händelsenamn utlöser den lämpliga mätaren.

timestamp

string

ISO 8601-tidsstämpel när händelsen inträffade. Standardvärde är aktuell tid om det inte anges.

metadata

object

Ytterligare egenskaper för filtrering och aggregering. Inkludera alla värden som refereras i din mätare “Över egenskap” eller filtreringsvillkor.

Exempel på användningsevenemangs-API

Skicka användningsevenemang till dina konfigurerade mätare med hjälp av Events API:

const response = await fetch('https://test.dodopayments.com/events/ingest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DODO_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
        }
      }
    ]
  })
});

Analys av användningsbaserad fakturering

Övervaka och analysera dina data för användningsbaserad fakturering med en omfattande analysinstrumentpanel. Spåra kundens konsumtionsmönster, mätarens prestanda och faktureringstrender för att optimera din prissättningsstrategi och förstå användningsbeteenden.

Översiktsanalys

Översiktsfliken ger en omfattande vy av din prestanda för användningsbaserad fakturering:

Aktivitetsmått

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

Aktuell månad

metric

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

All tid

metric

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

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

Mätarantaldiagram

Mätarantaldiagrammet 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 skalar automatiskt baserat på din användningsvolym och valt tidsintervall, vilket ger tydlig insyn i både små fluktuationer och stora förändringar i användning.

Händelseanalys

Händelsefliken ger detaljerad insyn i individuella användningsevenemang:

Visning av händelseinformation

Händelsetabellen ger en tydlig vy av individuella användningsevenemang med följande kolumner:

Händelsenamn: Den specifika åtgärden eller utlösaren som genererade användningsevenemanget
Händelse-ID: Unik identifierare för varje händelseinstans
Kund-ID: Kunden kopplad till händelsen
Tidsstämpel: När händelsen inträffade

Denna vy gör att du kan spåra och övervaka individuella användningsevenemang över din kundbas, vilket ger insyn i faktureringsberäkningar och användningsmönster.

Kundanalys

Kundfliken ger en detaljerad tabellvy av kundens användningsdata med följande information:

Tillgängliga datakolumner

Kundens e-post

string

E-postadress till kunden för identifiering.

Prenumerations-ID

string

Unik identifierare för kundens prenumeration.

Gratis tröskel

number

Antal gratis enheter som ingår i kundens plan innan avgifter tillämpas.

Pris per enhet

currency

Kostnaden per enhet för användning utöver den gratis tröskeln.

Senaste händelse

timestamp

Tidsstämpel för kundens senaste användningsevenemang.

Totalt pris

currency

Totalt belopp debiterat kunden för användningsbaserad fakturering.

Förbrukade enheter

number

Totalt antal enheter som kunden har förbrukat.

Debiterbara enheter

number

Antal enheter som överskrider den gratis tröskeln och debiteras.

Tabellfunktioner

Kolumnfiltrering: Använd funktionen “Redigera kolumner” för att visa/dölja specifika datakolumner
Realtidsuppdateringar: Användningsdata återspeglar de mest aktuella konsumtionsmåtten

Aggregeringsexempel

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

Förstå aggregeringstyper

Olika aggregeringstyper tjänar olika faktureringsscenarier. Välj rätt typ baserat på hur du vill mäta och ta betalt för användning.

Praktiska implementeringsexempel

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

Antalsaggregering - API-anrop

Scenario: Spåra det totala antalet API-förfrågningarMätarkonfiguration:

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

Exempelhä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 debiterade kunden

Summaaggregering - Datatransfer

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

Händelsenamn: data.transfer
Aggregeringstyp: Summa
Över egenskap: bytes
Mätningsenhet: GB

Exempelhä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 totalt överförd debiterad kunden

Maxaggregering - Maximalt antal samtidiga användare

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

Händelsenamn: concurrent.users
Aggregeringstyp: Max
Över egenskap: count
Mätningsenhet: users

Exempelhä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 maximala samtidiga användare debiterade kunden

Exempel på händelsefiltrering

Filtrera efter API-slutpunkt
Filtrera efter värdeintervall
Komplexa fler-villkorsfilter

Räkna endast API-anrop till specifika slutpunkter:Filtreringskonfiguration:

Egenskap: endpoint
Jämförare: equals
Värde: /v1/orders

Exempelhändelse:

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

Resultat: Händelser som matchar filtreringskriterierna skulle räknas. Händelser med olika slutpunkter skulle ignoreras.

Räkna endast stora filuppladdningar:Filtreringskonfiguration:

Egenskap: file_size
Jämförare: greater_than
Värde: 1048576 (1MB i byte)

Exempelhä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 1MB skulle räknas. Mindre filer skulle ignoreras.

Räkna premium API-anrop under kontorstid:Filtreringskonfiguration (med OCH-logik):

Egenskap: plan_type, Jämförare: equals, Värde: premium
Egenskap: hour, Jämförare: greater_than_or_equal, Värde: 9
Egenskap: hour, Jämförare: less_than, Värde: 17

Exempelhä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 (9 AM - 5 PM) skulle räknas.

Felsökning

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

Vanliga problem

De flesta problem med användningsbaserad fakturering faller inom dessa kategorier:

Problem med händelseleverans och bearbetning
Problem med mätarkonfiguration
Fel med datatyp och formatering
Problem med kund-ID och autentisering

Felsökningssteg

När du felsöker användningsbaserad fakturering:

Verifiera händelseleverans i fliken Händelseanalys
Kontrollera att mätarkonfigurationen matchar din händelsestruktur
Validera kund-ID och API-autentisering
Granska filtreringsvillkor och aggregeringsinställningar

Lösningar och fixar

Händelser visas inte i mätaren

Vanliga orsaker:

Händelsenamnet matchar inte exakt mätarkonfigurationen
Filtreringsvillkoren utesluter dina händelser
Kund-ID finns inte i ditt Dodo Payments-konto
Händelsens tidsstämpel ligger utanför den aktuella faktureringsperioden

Lösningar:

Verifiera stavningen av händelsenamnet och skiftlägeskänslighet
Granska och testa dina filtreringsvillkor
Bekräfta att kund-ID är giltigt och aktivt
Kontrollera att händelsetidsstämplarna är aktuella och korrekt formaterade

Aggregering fungerar inte som förväntat

Vanliga orsaker:

Över egenskapsnamnet matchar inte händelsemetadata-nycklar
Metadata-värden har fel datatyp (sträng vs nummer)
Saknade nödvändiga metadata-egenskaper

Lösningar:

Se till att metadata-nycklarna exakt matchar din inställning för Över egenskap
Konvertera strängnummer till faktiska nummer i dina händelser
Inkludera alla nödvändiga egenskaper i varje händelse

Filtrering fungerar inte

Vanliga orsaker:

Filtrerings egenskapsnamn matchar inte händelsemetadata
Fel jämförare för datatyp (sträng vs nummer)
Skiftlägeskänslighet i strängjämförelser

Lösningar:

Dubbelkolla att egenskapsnamnen matchar exakt
Använd lämpliga jämförare för dina datatyper
Tänk på skiftlägeskänslighet när du filtrerar strängar

Integration Guides

Cookbooks

Integrationsguide för användningsbaserad fakturering

API-referens - Händelseinmatning

API-referens - Skapande av mätare

Skapa en mätare

Steg-för-steg skapande av mätare

Länka mätare i en produkt

Produktkonfigurationsprocess

Skicka användningsevenemang

Händelsestruktur

Exempel på användningsevenemangs-API

Analys av användningsbaserad fakturering

Översiktsanalys

Aktivitetsmått

Mätarantaldiagram

Händelseanalys

Visning av händelseinformation

Kundanalys

Tillgängliga datakolumner

Tabellfunktioner

Aggregeringsexempel

Förstå aggregeringstyper

Praktiska implementeringsexempel

Exempel på händelsefiltrering

Felsökning

Vanliga problem

Felsökningssteg

Lösningar och fixar

Integration Guides

Cookbooks

API-referens - Händelseinmatning

API-referens - Skapande av mätare

​Skapa en mätare

​Steg-för-steg skapande av mätare

​Länka mätare i en produkt

​Produktkonfigurationsprocess

​Skicka användningsevenemang

​Händelsestruktur

​Exempel på användningsevenemangs-API

​Analys av användningsbaserad fakturering

​Översiktsanalys

​Aktivitetsmått

​Mätarantaldiagram

​Händelseanalys

​Visning av händelseinformation

​Kundanalys

​Tillgängliga datakolumner

​Tabellfunktioner

​Aggregeringsexempel

​Förstå aggregeringstyper

​Praktiska implementeringsexempel

​Exempel på händelsefiltrering

​Felsökning

​Vanliga problem

​Felsökningssteg

​Lösningar och fixar

Skapa en mätare

Steg-för-steg skapande av mätare

Länka mätare i en produkt

Produktkonfigurationsprocess

Skicka användningsevenemang

Händelsestruktur

Exempel på användningsevenemangs-API

Analys av användningsbaserad fakturering

Översiktsanalys

Aktivitetsmått

Mätarantaldiagram

Händelseanalys

Visning av händelseinformation

Kundanalys

Tillgängliga datakolumner

Tabellfunktioner

Aggregeringsexempel

Förstå aggregeringstyper

Praktiska implementeringsexempel

Exempel på händelsefiltrering

Felsökning

Vanliga problem

Felsökningssteg

Lösningar och fixar