Credit-Based Billing

Documentation Index

Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt

Use this file to discover all available pages before exploring further.

​

ما هو نظام الفوترة القائم على الائتمان؟

• منصات الذكاء الاصطناعي وLLM: منح الرموز أو أرصدة التوليد لكل خطة
• خدمات API: تخصيص أرصدة مكالمات API مع تسعير التجاوز
• منصات البنية التحتية: إصدار ساعات حسابية أو أرصدة تخزين
• خدمات الاتصال: توفير أرصدة الرسائل أو الدقائق لكل اشتراك
• SaaS مع مستويات الاستهلاك: جمع الاستهلاك المدرج في مجموعات الأرصدة

​

المفاهيم الأساسية

​

أنواع الأرصدة

​

دورة حياة الأرصدة

​

مصادر المنح

​

إنشاء أرصدة

1

Navigate to Credits

اذهب إلى المنتجات في لوحة التحكم واختر علامة التبويب الأرصدة. انقر على إنشاء رصيد للبدء.

2

Configure Basic Information

أدخل اسم الرصيد - هذا هو المعرف الداخلي لديك للرصيد.

3

Set General Settings

اضبط نوع الرصيد وخصائص العرض:

​

Credit Type

string

مطلوب

اختر الوحدة المخصصة أو أرصدة العملة.

• الوحدة المخصصة - تحديد المقياس الخاص بك (رموز، مكالمات API، ساعات حساب). يتطلب اسم الوحدة (مثل، “رموز المنصة”) وإعداد الدقة.
• أرصدة العملة - تمثل الأرصدة قيمة نقدية فعلية. يتطلب اختيار وحدة العملة (USD، EUR، GBP، INR، إلخ).

​

Unit Name

string

فقط للأرصدة بوحدة مخصصة. يُظهر التصنيف الذي يراه العملاء لهذه الأرصدة (مثل، “رموز الذكاء الاصطناعي”, “مكالمات API”). يظهر عند الفحص وفي بوابة العملاء.

​

Precision

number

فقط للأرصدة بوحدة مخصصة. عدد المنازل العشرية المسموح بها:

• 0 - الأعداد الصحيحة (الأفضل للعناصر المعدودة مثل مكالمات API)
• 1 - منزلة عشرية واحدة (0.0)
• 2 - منزلتان عشريتان (0.00) - الافتراضي
• 3 - ثلاث منازل عشرية (0.000)

لا يمكن تغيير الدقة بعد إنشاء الرصيد.

​

Credit Expiry

string

مدة صلاحية الأرصدة بعد إصدارها:

• 7 أيام، 30 يومًا (افتراضي)، 60 يومًا، 90 يومًا، مخصص، أو أبدًا

اختر مخصص لتحديد عدد الأيام المخصص (الحد الأدنى 1).

4

Configure Subscription Settings (Optional)

هذه الإعدادات تتحكم في سلوك الأرصدة داخل الاشتراكات المتكررة:

​

Rollover

boolean

السماح بترحيل الأرصدة غير المستخدمة إلى دورة الفوترة التالية. عند التمكين، قم بتكوين:

• نسبة الترحيل القصوى (0–100%) - الحد من مقدار الترحيل
• إطار زمني للترحيل - مدة صلاحية الأرصدة المرحلة (مثل، 1 شهر)
• عدد مرات الترحيل الأقصى - الحد الأقصى للترحيلات المتتالية قبل فقدان الأرصدة

عندما تنفد الأرصدة أو ينتهي الاشتراك:

​

Allow Overage

boolean

اسمح للعملاء بالاستمرار في استخدام خدمتك بعد أن يصل رصيدهم الائتماني إلى الصفر. عند التمكين، قم بتكوين:

• حد التجاوز - الحد الأقصى للأرصدة التي يمكن للعملاء استهلاكها بالإضافة إلى رصيدهم
• السعر لكل وحدة - تكلفة الرصيد الإضافي عندما يكون التجاوز ممكنًا (مع محدد العملة)

​

Overage Behavior

string

مطلوب

يتحكم في كيفية التعامل مع التجاوز في نهاية دورة الفوترة:

• اعفاء التجاوز عند إعادة التعيين (افتراضي) - يتم تتبع الاستخدام الذي يتجاوز حد الائتمان ولكن ليس مفوترًا. يتم إعادة تعيين الرصيد كل دورة.
• فوترة التجاوز في الفوترة - يتم شحن الاستخدام الذي يتجاوز حد الائتمان في الفاتورة القادمة، ثم يتم إعادة تعيين الرصيد.
• ترحيل العجز - يتم ترحيل الاستخدام الذي يتجاوز حد الائتمان كرصيد سلبي إلى الدورة التالية.
• ترحيل العجز (سداد تلقائي) - يتم ترحيل العجز إلى الأمام ويتم سداده تلقائيًا من الأرصدة الجديدة في الدورة القادمة.

5

Create Credit

انقر على إنشاء رصيد للحفظ. الرصيد الآن متاح للإرفاق بأي منتج.

استحقاق رصيدك جاهز. قم بإرفاقه بالمنتجات للبدء في إصدار الأرصدة للعملاء.

​

إرفاق الأرصدة بالمنتجات

​

منتجات الاشتراك

1

Create or Edit a Subscription Product

انتقل إلى المنتجات → إنشاء منتج أو قم بتعديل منتج موجود. اختر الاشتراك كنوع التسعير وقم بإعداد السعر المتكر.

2

Open Entitlements Section

قم بتوسعة قسم الاستحقاقات وانقر على زر إرفاق بجوار الأرصدة.

3

Select Credits to Attach

تفتح لوحة إضافة أرصدة. يمكنك اختيار رصيد موجود من القائمة المنسدلة أو النقر على إنشاء رصيد جديد لتعريف واحد على الفور.

يمكنك إرفاق حتى 3 أرصدة لكل منتج. يمكن أن يكون لكل رصيد تكوينه الخاص.

4

Configure Credit Settings

لكل رصيد مرفق، قم بإعداد:

​

Credits issued per billing cycle

number

مطلوب

عدد الأرصدة الممنوحة للعميل في كل فترة فوترة.

​

Low Balance Threshold

number

الإشعار عند انخفاض الرصيد عن هذا المبلغ. مفيد لتنبيه العملاء قبل نفادهم.

​

Credits During Free Trial

number

تعيين مبلغ مختلف للرصيد لفترات التجربة. تمكين انتهاء صلاحية أرصدة التجربة بعد انتهاء التجربة لإلغاء الأرصدة غير المستخدمة عند التحويل إلى اشتراك مدفوع.

​

Allow Proration

boolean

تناسب الأرصدة المتبقية عند ترقية أو تخفيض خطة الاشتراك الخاصة بالعميل.

​

Import Default Credit Settings

boolean

استخدم افتراضات الترحيل، التجاوز، والانتهاء من استحقاق الرصيد. قم بإيقاف هذه الإعدادات لتخصيصها خصيصًا لهذا المنتج.

5

Review and Add

راجع الرصيد المرفق الذي يظهر الاسم، الكمية، والانتهاء. انقر على إضافة إلى الاشتراك للتأكيد.

​

منتجات الدفع لمرة واحدة

1

Create a One-Time Product

أنشئ منتجًا بنوع التسعير دفع فردي.

2

Attach Credits

افتح قسم الاستحقاقات وارفق الأرصدة. قم بتكوين عدد الأرصدة المُصدرة (الإجمالي لمرة واحدة) عند الشراء.

​

منتجات الفوترة القائمة على الاستخدام

1

Create a Usage-Based Product

اختر الفوترة القائمة على الاستخدام كنوع التسعير. قم بإعداد السعر الأساسي وتكرار الفوترة.

2

Add a Meter

انقر على زر + في قسم اختر العداد لإضافة عداد. يمكن أن يحتوي الاشتراك على ما يصل إلى 3 عدادات.

3

Enable Credit Billing on the Meter

تفعيل فوتر الاستهلاك بالأرصدة لإرفاق رصيد بالعداد. اختر استحقاق الرصيد من القائمة المنسدلة.

​

Free Threshold

number

مطلوب

عدد الوحدات المجانية قبل أن تبدأ خصم الرصيد.

​

Bill usage in Credits

boolean

عند التمكين، يخصم عداد الاستخدام من رصيد العميل بدلاً من الشحن لكل وحدة.

​

Meter units per credit

number

مطلوب

عدد وحدات الاستخدام المطلوبة لخصم 1 رصيد. على سبيل المثال، إذا تم التعين على 1000، فإن 1,000 مكالمة API تستهلك 1 رصيد.

4

Configure Credit Issuance

حدد عدد الأرصدة الصادرة وقم بتخصيص إعدادات الرصيد لهذا المنتج بشكل اختياري.

5

Verify Attachment

بمجرد التكوين، يظهر العداد اسم الرصيد المرفق، سعر الوحدة، والحد المجاني.

​

إعدادات الرصيد

​

الترحيل

​

التجاوز

​

انتهاء الصلاحية

​

فوترة الاستخدام مع الأرصدة

​

كيف يعمل خصم الرصيد بناءً على العداد

1. يرسل تطبيقك أحداث الاستخدام - يتضمن كل حدث معرف العميل، اسم الحدث، والبيانات التعريفية
2. العدادات تجمع الأحداث - باستخدام التجميع: Count, Sum, Max, Last, أو Unique Count
3. تخصم الأرصدة تلقائيًا - يقوم عامل خلفية بمعالجة الأحداث كل دقيقة، ويحول وحدات العداد إلى أرصدة باستخدام المعدل المكون، ويخصم من رصيد العميل حسب ترتيب FIFO (الأقدم أولاً)
4. يتتبع التجاوز - إذا وصل الرصيد الائتماني إلى الصفر وتم تمكين التجاوز، يتتبع النظام الاستخدام التجاوزي للفوترة في نهاية الدورة

​

لوحة العدادات

​

تجربة العملاء

​

الفحص

​

بوابة العملاء

• الرصيد المتاح - الرصيد الحالي معروض بوضوح
• علامات التبويب للأرصدة - التبديل بين أنواع الأرصدة المختلفة (مثل، “أرصدة OpenAI”, “رموز الاستخدام”)
• المعاملات الأخيرة - سجل كامل بالتاريخ، معرف المعاملة، النوع، المبلغ، والرصيد الجاري

​

تفاصيل الاشتراك

• تخصيص الرصيد لكل دورة فوترة (مثل، “1000 أرصدة لكل دورة”)
• الرصيد المتبقي (مثل، “7500 أرصدة متبقية”)
• تاريخ التجديد لإصدار الرصيد القادم
• تبويب سجل الاستخدام مع توزيع مستوى العداد يظهر الوحدات المستهلكة، العتبات، أسعار الوحدات، والتكاليف الإجمالية

​

تفاصيل المعاملة

​

إدارة الأرصدة

​

عرض لوحة التحكم

​

قائمة استحقاقات الأرصدة

​

تفاصيل الأرصدة للعملاء

• محدد الرصيد - التبديل بين استحقاقات الائتمان المختلفة
• الرصيد المتاح - الرصيد الحالي ظاهر بوضوح، عرض بارز
• تطبيق الائتمان/الخصم - زر لتعديل رصيد العميل يدويًا
• المعاملات الأخيرة - دفتر الأستاذ الكامل مع التاريخ، معرف المعاملة، النوع، المبلغ، والرصيد الجاري

​

التعديلات اليدوية

​

دفتر الأستاذ الائتماني

​

Webhooks

​

إدارة API

​

مثال تكامل

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
  environment: 'test_mode', // defaults to 'live_mode'
});

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_ai_pro_plan',
      quantity: 1,
    }
  ],
  customer: { email: 'customer@example.com' },
  return_url: 'https://yourapp.com/success'
});

await client.usageEvents.ingest({
  events: [{
    event_id: `gen_${Date.now()}`,
    customer_id: 'cus_abc123',
    event_name: 'ai.generation',
    timestamp: new Date().toISOString(),
    metadata: { model: 'gpt-4', tokens: 1500 }
  }]
});

​

أمثلة من الواقع

​

أفضل الممارسات

• ابدأ ببساطة: ابدأ بنوع واحد من الرصيد وبدون الترحيل. أضف التعقيد استنادًا إلى ملاحظات واستخدام العملاء.
• حدد التوقعات بوضوح: عرض تخصيصات الرصيد، الأرصدة المتبقية، وتسعير التجاوز بشكل بارز في صفحات المنتجات الخاصة بك وبوابة العملاء.
• استخدم وحدات ذات معنى: سمِّ الأرصدة بما تمثله (مثل، “مكالمات API”, “رموز AI”) بدلاً من المصطلحات العامة. يساعد ذلك العملاء على فهم القيمة.
• قم بتكوين الانتهاء بعناية: قد تدفع نوافذ الانتهاء القصيرة (7 أيام) للسرعة ولكن قد تحبط العملاء. النوافذ الأطول (30–90 يومًا) أكثر موافقة للعملاء لمعظم منتجات SaaS.
• مراقبة الأرصدة المنخفضة: ضع حدودًا منخفضة الرصيد لتنبيه العملاء قبل نفادها، مما يقلل من مفاجئات رسوم التجاوز.
• اختبار في وضع الاختبار: إنشاء أرصدة، إرفاقها بمنتجات اختبار، وتجربة دورة الشراء الكاملة → الاستخدام → الخصم → الانتهاء قبل بدء التنفيذ.