Kreditbaserad fakturering - Dodo Payments Documentation

Webhook-händelser för kreditbaserad fakturering

Följande webhook-händelser finns tillgängliga för att spåra förändringar i livscykeln för kreditbaserad fakturering. Dessa händelser gäller virtuella krediträttigheter (API-anrop, tokens, beräkningstimmar), inte Customer Wallets (monetära saldon).

Händelse	Beskrivning
`credit.added`	Krediter ges till en kund (via prenumeration, engångsköp, tillägg eller API)
`credit.deducted`	Krediter förbrukas genom användning eller manuell debitering
`credit.expired`	Oanvända krediter förfaller efter den konfigurerade förfalloperioden
`credit.rolled_over`	Oanvända krediter överförs till en ny tilldelning vid cykelslut
`credit.rollover_forfeited`	Krediter upphörde eftersom maxantalet överföringar uppnåddes
`credit.overage_charged`	Överkostnader tillämpas när användningen fortsätter bortom nollbalans
`credit.overage_reset`	Ackumulerade överkostnader återställs (till exempel, i början av en ny faktureringscykel)
`credit.manual_adjustment`	Manuell kredit- eller debeteringsjustering gjord via instrumentpanelen eller API
`credit.balance_low`	Kreditbalansen faller under det konfigurerade lågbalanströskelvärdet

Bokföringshändelser

Alla bokföringshändelser (credit.added genom credit.manual_adjustment) delar samma CreditLedgerEntryResponse-payload som dokumenteras i schemat nedan. Payloaden inkluderar ett metadata-fält som hämtas från källan för kreditgivningen — abonnemanget eller betalningen som skapades vid checkout. Detta låter dig använda plånbokskrediter baserat på din egen checkout metadata (till exempel, en orgId) istället för det av Dodo utfärdade customer_id: kreditgivningar från abonnemang visar abonnemangets metadata och kreditgivningar från betalning visar betalningens metadata. Fältet är tomt när kreditgivningen inte har någon lösbar källa (till exempel, krediter som ges direkt via API:et).

Lågbalansevenemang (credit.balance_low)

Evenemanget credit.balance_low använder en annan payload (CreditBalanceLowPayload) fokuserad på tröskelvarningar:

{
  "business_id": "bus_H4ekzPSlcg",
  "type": "credit.balance_low",
  "timestamp": "2025-08-04T06:15:00.000000Z",
  "data": {
    "payload_type": "CreditBalanceLow",
    "customer_id": "cus_8VbC6JDZzPEqfBPUdpj0K",
    "subscription_id": "sub_7EeHq2ewQuadropD2ra",
    "credit_entitlement_id": "cent_9xY2bKwQn5MjRpL8d",
    "credit_entitlement_name": "API Credits",
    "available_balance": "15",
    "subscription_credits_amount": "100",
    "threshold_percent": 20,
    "threshold_amount": "20"
  }
}

customer_id

string

Kunden vars kreditbalans utlöste varningen.

subscription_id

string

Abonnemanget associerat med denna krediträttighet.

credit_entitlement_id

string

Krediträttigheten som har låg balans.

credit_entitlement_name

string

Visningsnamn för krediträttigheten.

available_balance

string

Nuvarande kreditbalans vid tiden för varningen.

subscription_credits_amount

string

Totala krediter utfärdade per faktureringscykel för detta abonnemang.

threshold_percent

integer

Den konfigurerade lågbalanströskelprocenten.

threshold_amount

string

Den absoluta kreditbelopp som tröskeln motsvarar.

Använda `credit.balance_low` för Proaktiva Varningar

Använd webhook credit.balance_low för att meddela kunder innan de får slut på krediter:

app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'credit.balance_low') {
    const data = event.data;
    
    // Notify the customer their credits are running low
    await sendEmail(data.customer_id, {
      subject: `Your ${data.credit_entitlement_name} balance is running low`,
      body: `You have ${data.available_balance} credits remaining ` +
            `(${data.threshold_percent}% threshold reached). ` +
            `Consider upgrading your plan or purchasing additional credits.`
    });
    
    console.log(`Low balance alert for customer ${data.customer_id}`);
  }
  
  res.json({ received: true });
});

Prenumerera på credit.balance_low för att proaktivt varna kunder innan de förbrukar sina krediter. Kombinera med credit.deducted för att spåra realtidskonsumentmönster.

Get Customer Balance

Kontrollera en kunds nuvarande saldo via API.

Create Ledger Entry

Manuellt kreditera eller debitera en kunds saldo.

Webhook Payload-schema

Response for a ledger entry

amount

string

obligatorisk

balance_after

string

obligatorisk

balance_before

string

obligatorisk

brand_id

string

obligatorisk

Brand id this credit ledger entry belongs to

business_id

string

obligatorisk

created_at

string<date-time>

obligatorisk

credit_entitlement_id

string

obligatorisk

customer_id

string

obligatorisk

string

obligatorisk

is_credit

boolean

obligatorisk

metadata

object

obligatorisk

Metadata associated with the credit grant's source (the subscription or payment created at checkout). Empty when the grant has no resolvable source (e.g. credits granted directly via the API).

Show child attributes

overage_after

string

obligatorisk

overage_before

string

obligatorisk

transaction_type

enum<string>

obligatorisk

Tillgängliga alternativ:

credit_added,

credit_deducted,

credit_expired,

credit_rolled_over,

rollover_forfeited,

overage_charged,

overage_reset,

auto_top_up,

manual_adjustment,

refund

description

string | null

grant_id

string | null

reference_id

string | null

reference_type

string | null

​Webhook-händelser för kreditbaserad fakturering

​Bokföringshändelser

​Lågbalansevenemang (credit.balance_low)

​Använda credit.balance_low för Proaktiva Varningar

Get Customer Balance

Create Ledger Entry

​Webhook Payload-schema

Webhook-händelser för kreditbaserad fakturering

Bokföringshändelser

Lågbalansevenemang (credit.balance_low)

Använda `credit.balance_low` för Proaktiva Varningar

Webhook Payload-schema