الانتقال إلى المحتوى الرئيسي

أحداث الويب هوك للفوترة المعتمدة على الرصيد

الأحداث التالية للويب هوك متاحة لتعقب تغييرات دورة حياة الفوترة المعتمدة على الرصيد. تنطبق هذه الأحداث على استحقاقات الاعتماد الافتراضي (استدعاءات API، رموز مميزة، ساعات حوسبة)، ولا تنطبق على محافظ العملاء (الأرصدة النقدية).
الحدثالوصف
credit.addedيتم منح الاعتمادات للعميل (من خلال الاشتراك، أو عملية شراء لمرة واحدة، أو إضافة، أو API)
credit.deductedيتم استهلاك الاعتمادات من خلال الاستخدام أو الخصم اليدوي
credit.expiredتنتهي صلاحية الاعتمادات غير المستخدمة بعد فترة انتهاء الصلاحية المكوَّنة
credit.rolled_overتُرحَّل الاعتمادات غير المستخدمة إلى منحة جديدة عند نهاية الدورة
credit.rollover_forfeitedيتم مصادرة الاعتمادات لأن الحد الأقصى لعدد عمليات الترحيل قد تم بلوغه
credit.overage_chargedيتم تطبيق رسوم تجاوز عند استمرار الاستخدام بعد وصول الرصيد إلى الصفر
credit.manual_adjustmentتعديل يدوي على الاعتماد أو الخصم يتم عبر لوحة التحكم أو API
credit.balance_lowينخفض رصيد الاعتماد إلى ما دون الحد الأدنى المكوَّن

أحداث دفتر الأستاذ

تشترك جميع أحداث دفتر الأستاذ (credit.added وحتى credit.manual_adjustment) في نفس الحمولة CreditLedgerEntryResponse الموضحة في المخطط أدناه.

حدث انخفاض الرصيد (credit.balance_low)

يستخدم الحدث credit.balance_low حمولة مختلفة (CreditBalanceLowPayload) تركز على تنبيه العتبة:
{
  "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
العميل الذي أدى رصيده من الاعتماد إلى تشغيل التنبيه.
subscription_id
string
الاشتراك المرتبط بهذا الاستحقاق الاعتمادي.
credit_entitlement_id
string
الاستحقاق الاعتمادي الذي أصبح رصيده منخفضًا.
credit_entitlement_name
string
اسم العرض للاستحقاق الاعتمادي.
available_balance
string
الرصيد الحالي من الاعتماد وقت حدوث التنبيه.
subscription_credits_amount
string
إجمالي الاعتمادات الممنوحة خلال كل دورة فوترة لهذا الاشتراك.
threshold_percent
integer
نسبة حد الرصيد المنخفض المكوَّنة.
threshold_amount
string
مقدار الاعتماد المطلق الذي تتوافق معه العتبة.

استخدام credit.balance_low لتنبيهات استباقية

استخدم ويب هوك credit.balance_low لإخطار العملاء قبل نفاد اعتماداتهم:
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 });
});
اشترك في credit.balance_low لتنبيه العملاء استباقيًا قبل نفاد اعتماداتهم. اجمعه مع credit.deducted لتتبع أنماط الاستهلاك في الوقت الفعلي.

مخطط حمولة الويب هوك

Response for a ledger entry

amount
string
مطلوب
balance_after
string
مطلوب
balance_before
string
مطلوب
business_id
string
مطلوب
created_at
string<date-time>
مطلوب
credit_entitlement_id
string
مطلوب
customer_id
string
مطلوب
id
string
مطلوب
is_credit
boolean
مطلوب
overage_after
string
مطلوب
overage_before
string
مطلوب
transaction_type
enum<string>
مطلوب
الخيارات المتاحة:
credit_added,
credit_deducted,
credit_expired,
credit_rolled_over,
rollover_forfeited,
overage_charged,
auto_top_up,
manual_adjustment,
refund
description
string | null
grant_id
string | null
reference_id
string | null
reference_type
string | null