Credit-Based Billing - Dodo Payments Documentation

يتيح لك Credit-Based Billing منح العملاء رصيدًا من الاعتمادات—مثل استدعاءات API أو الرموز المميزة أو وحدات الحوسبة أو أي مقياس مخصص—والخصم من هذا الرصيد أثناء استخدامهم لخدمتك. تعمل الاعتمادات مع جميع أنواع المنتجات: الاشتراكات وعمليات الشراء لمرة واحدة وعمليات الفوترة القائمة على الاستخدام.

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

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

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

صفحة الدفع تُظهر الرصيد المتضمن مع شراء المنتج — Credits appear as entitlements on your products and show in checkout, customer portal, and subscription details.

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

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

عند إنشاء ائتمان، تختار بين نوعين:

Custom Unit
Fiat Credits

حدّد الاعتمادات بوحدتك الخاصة—الرموز المميزة أو استدعاءات API أو ساعات الحوسبة أو أي مقياس ذي معنى لمنتجك. تستخدم الوحدات المخصصة مستوى الدقة الذي تحدده (من 0 إلى 10 منازل عشرية).الأفضل لـ: مكالمات API، رموز الذكاء الاصطناعي، ساعات الحساب، وحدات التخزين، الرسائل

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

تتبع الأرصدة دورة حياة واضحة من الإصدار إلى الاستهلاك:

Credits Issued

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

Credits Consumed

أثناء استخدام العملاء لخدمتك، تُخصم الأرصدة. للمنتجات القائمة على الاستخدام، تقوم العدادات تلقائيًا بخصم الأرصدة بناءً على الأحداث في الوقت الفعلي. يمكنك أيضًا خصم الأرصدة يدويًا عبر لوحة التحكم أو API.

Credits Expire or Roll Over

في نهاية دورة الفوترة (أو بعد فترة انتهاء الصلاحية المقررة)، تنتهي صلاحية الأرصدة غير المستخدمة أو تُرحل إلى الفترة التالية بناءً على إعداداتك.

Overage Handling

إذا نفدت الاعتمادات في منتصف الدورة، يمكنك السماح بالاستخدام الإضافي (استمرار الاستخدام بعد نفاد الرصيد) واختيار طريقة التعامل معه: إعفاؤه أو إصدار فاتورة به أو ترحيل العجز إلى الأمام.

مصادر المنح

يمكن منح الأرصدة من مصادر متعددة:

المصدر	الوصف
الاشتراك	أرصدة تُصدر عند شراء اشتراك، ويُعاد إصدارها في كل دورة فوترة
لمرة واحدة	أرصدة تُصدر مع منتج يتم الدفع مقابله لمرة واحدة
إضافة	أرصدة تُصدر مع إضافة مرفقة باشتراك
API	أرصدة تُمنح يدويًا عبر API أو لوحة التحكم
ترحيل	أرصدة مُرحّلة من دورة فوترة سابقة

إنشاء أرصدة

أنشئ استحقاقات الأرصدة في قسم المنتجات → الأرصدة في لوحة التحكم الخاصة بك. يُعرّف كل رصيد الوحدة، الدقة، قواعد انتهاء الصلاحية، وسلوك دورة الحياة.

صفحة قائمة الأرصدة تُظهر الاعتمادات المُنشأة — The Credits tab under Products shows all your credit entitlements.

Navigate to Credits

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

Configure Basic Information

أدخل Credit Name—وهو المعرّف الداخلي للاعتماد.

نموذج إنشاء الرصيد يُظهر المعلومات الأساسية والإعدادات العامة وإعدادات الاشتراك — The credit creation form with all configuration sections.

Set General Settings

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

string

مطلوب

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

Custom Unit: حدّد مقياسك الخاص (الرموز المميزة أو استدعاءات API أو ساعات الحوسبة). يتطلب ذلك Unit Name (مثل “Platform tokens”) وإعداد Precision.
Fiat Credits: تمثل الاعتمادات قيمة نقدية حقيقية. يتطلب ذلك اختيار Unit Currency (USD أو EUR أو GBP أو INR وغير ذلك).

string

للاعتمادات من نوع Custom Unit فقط. التسمية التي يراها العملاء لهذا الاعتماد (مثل “AI Tokens” أو “API Calls”). تظهر في صفحة الدفع وCustomer Portal.

number

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

0: أعداد صحيحة (مناسبة للعناصر القابلة للعد مثل استدعاءات API)
1: منزلة عشرية واحدة (0.0)
2: منزلتان عشريتان (0.00)—الإعداد الافتراضي
3: ثلاث منازل عشرية (0.000)
حتى 10: للوحدات عالية الدقة (مثل الرموز المميزة الكسرية أو الاستخدام الجزئي)

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

string

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

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

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

Configure Subscription Settings (Optional)

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

boolean

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

Max Rollover Percentage (من 0 إلى 100%): حدّد مقدار ما يمكن ترحيله
Rollover Timeframe: المدة التي تظل خلالها الاعتمادات المُرحّلة صالحة (مثل شهر واحد)
Max Rollover Count: الحد الأقصى لعمليات الترحيل المتتالية قبل مصادرة الاعتمادات

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

boolean

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

Overage Limit: الحد الأقصى للاعتمادات التي يمكن للعملاء استهلاكها بعد تجاوز رصيدهم
Price Per Unit: تكلفة كل اعتماد إضافي عند تفعيل الاستخدام الإضافي (مع محدد العملة)

string

مطلوب

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

Forgive overage at reset (الإعداد الافتراضي): يتم تتبع الاستخدام الذي يتجاوز حد الاعتمادات، لكن لا تتم فوترته. يُعاد ضبط الرصيد في كل دورة.
Bill overage at billing: تتم فوترة الاستخدام الذي يتجاوز حد الاعتمادات في الفاتورة التالية، ثم يُعاد ضبط الرصيد.
Carry over deficit: يُرحّل الاستخدام الذي يتجاوز حد الاعتمادات إلى الدورة التالية كرصيد سالب.
Carry over deficit (auto-repay): يُرحّل العجز إلى الأمام وتتم تسويته تلقائيًا من الاعتمادات الجديدة في الدورة التالية.

Create Credit

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

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

ابدأ بإعدادات بسيطة - بدون ترحيل، بدون تجاوز - وأضف التعقيد كلما تعلمت كيف يستخدم العملاء الأرصدة. يمكن تحديث معظم الإعدادات في أي وقت دون التأثير على المنح الحالية. لاحظ أنه لا يمكن تغيير الدقة بعد إنشاء الرصيد.

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

يتم إرفاق النقاط بالمنتجات كـ حقوق في عملية إنشاء أو تحرير المنتج. يمكنك إرفاق ما يصل إلى 5 نقاط لكل منتج. تعمل النقاط مع جميع أنواع التسعير الثلاثة.

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

بالنسبة للاشتراكات، تُصدر الأرصدة لكل دورة فوترة ويمكن إعدادها بالبرورطة، وأرصدة التجربة، وإعدادات الدورة المحددة.

Create or Edit a Subscription Product

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

Open Entitlements Section

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

قسم حقوق المنتج يُظهر زر إرفاق الأرصدة — The Entitlements section in the product form with Credits, License Key, and Digital Product Delivery options.

Select Credits to Attach

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

لوحة إضافة الأرصدة مع قائمة اختيار الأرصدة — The Add Credits panel lets you select existing credits or create new ones.

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

Configure Credit Settings

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

number

مطلوب

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

number

إرسال إشعار عندما ينخفض الرصيد إلى أقل من هذه النسبة المئوية (0–100). مفيد لتنبيه العملاء قبل نفاد رصيدهم.

number

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

boolean

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

boolean

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

نموذج تكوين الأرصدة مع إعدادات دورة الفوترة والتجربة والتوزيع — Credit configuration showing per-cycle amount, trial credits, proration, and custom settings.

Review and Add

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

لوحة إضافة الأرصدة تُظهر الرصيد المُختار مع التفاصيل — Review attached credits before adding them to the subscription.

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

بالنسبة للمدفوعات لمرة واحدة، تُصدر الأرصدة مرة واحدة في وقت الشراء.

Create a One-Time Product

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

قسم تسعير المنتج مع اختيار الدفع الأحادي — Single Payment pricing selected for a one-time credit product.

Attach Credits

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

الأرصدة للمنتجات لمرة واحدة مثالية لحزم تزويد الرصيد، الحزم الترويجية، أو مشتريات الرصيد المسبق.

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

بالنسبة للمنتجات القائمة على الاستخدام، ترتبط الأرصدة بـ عدادات وتُخصم تلقائيًا بناءً على أحداث الاستهلاك في الوقت الفعلي.

Create a Usage-Based Product

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

تكوين تسعير الفوترة حسب الاستخدام — Usage Based Billing pricing type with meter configuration.

Add a Meter

انقر على الزر + في قسم Select meter لإضافة مقياس. يمكن أن يحتوي الاشتراك على ما يصل إلى 50 مقياسًا.

لوحة اختيار العداد تُظهر الحد المجاني وتبديل الأرصدة — The Select Meter panel with meter configuration and credit toggle.

Enable Credit Billing on the Meter

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

number

ينطبق ذلك فقط عندما يفوتر المقياس مبالغ مالية. وعندما يفوتر المقياس بالاعتمادات، يُخصم كل عنصر من رصيد الاعتمادات.

boolean

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

number

مطلوب

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

تكوين العداد مع اختيار الأرصدة ووحدات العداد لكل رصيد — Credit attached to a meter with per-unit conversion rate.

Configure Credit Issuance

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

تكوين الأرصدة لمنتج الفوترة حسب الاستخدام — Configure how many credits to issue and whether to use default settings.

Verify Attachment

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

العداد المُكون يُظهر تفاصيل إرفاق الأرصدة — Meter with credit attached showing price, threshold, and credit name.

عند ربط الاعتمادات بالمقاييس، يخصم النظام الاعتمادات تلقائيًا استنادًا إلى أحداث الاستخدام المستلمة. يعالج عامل يعمل في الخلفية الأحداث كل دقيقة، ويجمعها وفقًا لإعدادات المقياس، ويطبّق الخصم وفق FIFO (الوارد أولًا، الصادر أولًا) من المنح غير منتهية الصلاحية للعميل، بدءًا بالمنحة التي تنتهي صلاحيتها أولًا.

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

الترحيل

يتيح الترحيل للأرصدة غير المستخدمة الترحيل إلى دورة الفوترة التالية بدلاً من انتهائها.

الإعداد	الوصف
الترحيل ممكن	تبديل للسماح بترحيل الأرصدة غير المستخدمة
نسبة الترحيل القصوى	الحد من مقدار الترحيل (0–100%). إذا كانت 50%، يترحل النصف فقط من الأرصدة غير المستخدمة
إطار زمني للترحيل	مدة صلاحية الأرصدة المرحلة (يوم، أسبوع، شهر، سنة)
عدد مرات الترحيل الأقصى	عدد المرات القصوى التي يمكن ترحيل الأرصدة فيها بشكل متتال. بعد هذا الحد، تفقد الأرصدة المتبقية

مثال: لدى العميل 200 رصيد غير مستخدم في نهاية الدورة. مع ترحيل 75%، يترحل 150 رصيدًا ويفقد 50.

التجاوز

يتحكم التجاوز في ما يحدث عندما يصل رصيد العميل الائتماني إلى الصفر خلال الدورة.

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

خيارات سلوك التجاوز:

السلوك	الوصف
Forgive overage at reset	يتم تتبع الاستخدام الذي يتجاوز حد الاعتمادات، لكن لا تتم فوترته. يُعاد ضبط الرصيد في كل دورة
Bill overage at billing	تتم فوترة الاستخدام الذي يتجاوز حد الاعتمادات في الفاتورة التالية، ثم يُعاد ضبط الرصيد
Carry over deficit	يُرحّل الاستخدام الإضافي إلى الدورة التالية كرصيد سالب
Carry over deficit (auto-repay)	يُرحّل العجز إلى الأمام وتتم تسويته تلقائيًا من الاعتمادات الجديدة في الدورة التالية

لا يمنع Dodo Payments الاستخدام عندما يصل الرصيد إلى الصفر. إذا كنت لا تريد أن يواصل العملاء استخدام الخدمة دون اعتمادات، فتحقق من الرصيد في تطبيقك قبل معالجة الطلب. اختر سلوك الاستخدام الإضافي الذي يتوافق مع نموذج الفوترة لديك. يُعد Forgive at reset الخيار الافتراضي والأبسط.

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

الإعداد	الوصف
Credit Expiry	المدة بعد الإصدار التي تنتهي بعدها صلاحية الاعتمادات (7 أو 30 أو 60 أو 90 يومًا، أو عدد أيام مخصص، أو دون انتهاء)
Trial Credits Expire After Trial	ما إذا كانت اعتمادات التجربة الخاصة تنتهي صلاحيتها عند انتهاء فترة التجربة

تنشئ الاعتمادات منتهية الصلاحية قيدًا في دفتر الأستاذ credit_expired. إذا كان الترحيل مفعّلًا، تُطبّق نسبة الترحيل قبل انتهاء الصلاحية، وتنتهي صلاحية المتبقي فقط.

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

عند ربط الاعتمادات بمقاييس الاستخدام، ينشئ النظام نموذج فوترة قويًا قائمًا على الاستهلاك. يحصل العملاء على تخصيص من الاعتمادات، وتخصم أحداث الاستخدام تلقائيًا من رصيدهم.

لوحة معلومات الفوترة القائمة على الاستخدام تعرض جدول الأحداث مع الاعتمادات المستهلكة — The Usage Billing dashboard shows meter events with units consumed, credits consumed, and customer details.

كيفية عمل خصم الاعتمادات المستند إلى المقاييس

يرسل تطبيقك أحداث الاستخدام: يتضمن كل حدث معرّف العميل واسم الحدث والبيانات الوصفية
تجمع المقاييس الأحداث: باستخدام تجميع Count أو Sum أو Max أو Last
تُخصم الاعتمادات تلقائيًا: يعالج عامل يعمل في الخلفية الأحداث كل دقيقة، ويحوّل وحدات المقياس إلى اعتمادات باستخدام المعدل الذي أعددته، ويخصمها من رصيد العميل باستخدام ترتيب FIFO (المنح الأقرب إلى انتهاء الصلاحية أولًا)
يتم تتبع الاستخدام الإضافي: إذا وصل رصيد الاعتمادات إلى الصفر وكان الاستخدام الإضافي مفعّلًا، يتتبع النظام الاستخدام الإضافي لفوترته في نهاية الدورة

لوحة المقاييس

تتضمن لوحة معلومات الفوترة القائمة على الاستخدام لوحة Meters تعرض جميع المقاييس المحددة مع نوع التجميع الخاص بها:

التجميع	الوصف	مثال
Count	العدد الإجمالي للأحداث	استدعاءات API
Sum	مجموع حقل قيمة	إجمالي وحدات البايت المنقولة
Max	أعلى قيمة مسجلة	ذروة المستخدمين المتزامنين
Last	أحدث قيمة	مساحة التخزين المستخدمة حاليًا

تجربة العميل

صفحة الدفع

عندما يشتري العميل منتجًا تتضمنه اعتمادات مرتبطة، تعرض صفحة الدفع الاعتمادات المضمنة باعتبارها جزءًا من عرض المنتج.

تظهر الاعتمادات في قسم Includes أسفل وصف المنتج، مع عرض مقدار الاعتمادات ونوعها (مثل “$1000 API calls”).

Customer Portal

يمكن للعملاء عرض أرصدة اعتماداتهم وإدارتها في Customer Portal ضمن قسم Credits.

تعرض البوابة ما يلي:

Available Balance: الرصيد الحالي للاعتمادات معروض بشكل بارز
Credit Tabs: التبديل بين أنواع الاعتمادات المختلفة (مثل “OpenAI Credits” أو “Usage Tokens”)
Recent Transactions: السجل الكامل مع التاريخ ومعرّف المعاملة والنوع والمبلغ والرصيد الجاري

تشمل أنواع المعاملات المعروضة للعملاء ما يلي:

النوع	الوصف	المبلغ
Credits with Subscription	الاعتمادات الصادرة عند شراء الاشتراك أو تجديده	أخضر (+)
One-Time Credits	الاعتمادات الناتجة عن عمليات الشراء لمرة واحدة أو المنح اليدوية	أخضر (+)
Usage Deduction	الاعتمادات المستهلكة من خلال استخدام الخدمة	أحمر (−)
Overage	الاستخدام الذي يتجاوز رصيد الاعتمادات	أحمر (−)

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

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

المعلومات الرئيسية المعروضة:

Credit allocation لكل دورة فوترة (مثل “1000 credits each cycle”)
Remaining balance (مثل “7500 credits remaining”)
Renewal date لإصدار الاعتمادات التالي
علامة تبويب Usage History مع تفاصيل على مستوى المقياس تعرض الوحدات المستهلكة والحدود وأسعار الوحدات والتكاليف الإجمالية

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

تتضمن صفحات معاملات الدفع قسم Entitlements يعرض جميع الاستحقاقات المقدمة مع الدفعة، بما في ذلك الاعتمادات.

إدارة الاعتمادات

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

قائمة استحقاقات الاعتمادات

اعرض جميع استحقاقات اعتماداتك في Products → Credits. يعرض الجدول اسم الاعتماد وإعدادات انتهاء الصلاحية، ويوفر إجراءات سريعة للتحرير أو الأرشفة.

صفحة قائمة الاعتمادات في قسم المنتجات — Credits listing with total count, creation button, and management actions.

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

اعرض أرصدة اعتمادات عميل محدد وسجل معاملاته من Customers → [Customer Name] → Credits.

صفحة تفاصيل العميل مع علامة تبويب Credits التي تعرض الرصيد والمعاملات — Customer detail page showing credit balance and full transaction ledger.

يتضمن عرض اعتمادات العميل ما يلي:

Credit Selector - التبديل بين استحقاقات الاعتمادات المختلفة
Available Balance - الرصيد الحالي معروض بحجم كبير وبشكل بارز
Apply Credit/Debit - زر لتعديل رصيد العميل يدويًا
Recent Transactions - دفتر الأستاذ الكامل مع التاريخ ومعرّف المعاملة والنوع والمبلغ والرصيد الجاري

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

يمكنك إضافة الاعتمادات إلى رصيد العميل أو خصمها منه يدويًا مباشرةً من لوحة المعلومات:

Navigate to Customer

انتقل إلى Customers وحدد العميل.

Open Credits Tab

انقر على علامة تبويب Credits وحدد استحقاق الاعتمادات المناسب من محدد المحفظة.

Apply Credit or Debit

انقر على Apply Credit/Debit لفتح واجهة التعديل.

string

مطلوب

حدد Credit لإضافة اعتمادات أو Debit لإزالتها من رصيد العميل.

number

مطلوب

عدد الاعتمادات المراد إضافتها أو إزالتها.

string

شرح اختياري للتعديل (مثل “Service compensation” أو “Promotional bonus”).

Confirm

راجع التعديل وطبّقه. يظهر التغيير فورًا في رصيد العميل ويُسجّل في دفتر أستاذ الاعتمادات.

تنشئ التعديلات اليدوية قيدًا في دفتر الأستاذ manual_adjustment مع سجل تدقيق كامل.

دفتر أستاذ الاعتمادات

تُسجّل كل عملية اعتماد في دفتر أستاذ الاعتمادات، ما يوفر سجل تدقيق كاملًا:

نوع المعاملة	الوصف
Credit Added	الاعتمادات الممنوحة (عبر الاشتراك أو الشراء لمرة واحدة أو API)
Credit Deducted	الاعتمادات المستهلكة من خلال الاستخدام أو الخصم اليدوي
Credit Expired	الاعتمادات التي انتهت صلاحيتها دون ترحيل
Credit Rolled Over	الاعتمادات المُرحّلة إلى الفترة التالية
Rollover Forfeited	الاعتمادات المُرحّلة التي صودرت بعد بلوغ الحد الأقصى لعدد عمليات الترحيل
Overage Charged	الاستخدام الذي يتجاوز رصيد الاعتمادات مع تفعيل الاستخدام الإضافي
Overage Reset	الاستخدام الإضافي المتتبّع الذي تم مسحه عند إعادة ضبط دورة الفوترة
Auto Top-Up	إعادة تعبئة الاعتمادات تلقائيًا عند انخفاض الرصيد
Manual Adjustment	اعتماد أو خصم يطبقه التاجر يدويًا
Refund	الاعتمادات المُستردة

يسجل كل قيد في دفتر الأستاذ الرصيد قبل المعاملة وبعدها، والاستخدام الإضافي قبل المعاملة وبعدها، ووصفًا، ومرجعًا إلى المصدر (الدفعة أو الاشتراك وغير ذلك).

Webhooks

يُطلق Credit-Based Billing أحداث Webhook لكل تغيير في دورة حياة الاعتماد. استخدمها لمزامنة تطبيقك مع أرصدة الاعتمادات، أو لتفعيل الإشعارات، أو لإنشاء مهام سير عمل مخصصة للفوترة.

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

تتضمن جميع أحداث دفتر الأستاذ (كل حدث credit.* باستثناء credit.balance_low) حمولة CreditLedgerEntry كاملة تتضمن الرصيد قبل المعاملة وبعدها، والاستخدام الإضافي قبل المعاملة وبعدها، ومرجع المصدر، وmetadata لاشتراك المصدر أو دفعة المنحة (ويكون فارغًا للمنح التي أُنشئت مباشرةً عبر API). ويتضمن حدث credit.balance_low إعداد الحد والرصيد الحالي.

Credit Webhook Payloads

اعرض مخططات الحمولة الكاملة وأوصاف الحقول وأمثلة التكامل لجميع أحداث Webhook الخاصة بالاعتمادات.

إدارة API

Create Credit Entitlements

استخدم API لإنشاء استحقاقات الاعتمادات برمجيًا مع تحكم كامل في إعدادات الترحيل والاستخدام الإضافي وانتهاء الصلاحية.

Create Credit Entitlement

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

List Credit Entitlements

استرجع جميع استحقاقات الاعتمادات لنشاطك التجاري.

Manage Credit Entitlements

استرجع استحقاقات الاعتمادات أو حدّثها أو احذفها. يمكن استعادة الاستحقاقات المحذوفة.

Get Credit Entitlement

استرجع استحقاق اعتماد محددًا باستخدام المعرّف الخاص به.

Update Credit Entitlement

حدّث إعدادات الترحيل أو الاستخدام الإضافي أو انتهاء الصلاحية أو غيرها.

Delete Credit Entitlement

احذف استحقاق اعتماد حذفًا غير نهائي.

Undelete Credit Entitlement

استعد استحقاق اعتماد محذوفًا سابقًا.

Grant and Adjust Credits

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

Create Ledger Entry

أضف اعتمادًا إلى رصيد العميل أو اخصم منه مع سجل تدقيق كامل ودعم لخاصية idempotency.

Query Balances and Ledger

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

List Balances

اعرض جميع أرصدة العملاء لاستحقاق اعتماد.

Get Customer Balance

احصل على رصيد عميل محدد.

List Customer Grants

اعرض جميع منح الاعتمادات لعميل.

List Customer Ledger

سجل المعاملات الكامل لعميل.

مثال على التكامل

هيّئ عميل Dodo Payments:

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: 'pdt_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 }
  }]
});

أمثلة من العالم الحقيقي

AI SaaS Platform

هيكل التسعير:

الخطة	السعر	الاعتمادات/الشهر	الاستخدام الإضافي
Starter	$29/mo	10,000 رمز مميز	$0.003/رمز مميز
Pro	$99/mo	100,000 رمز مميز	$0.002/رمز مميز
Enterprise	$499/mo	1,000,000 رمز مميز	$0.001/رمز مميز

الإعداد:

نوع الاعتماد: Custom Unit (“AI Tokens”)
الدقة: 0 (رموز مميزة كاملة)
الترحيل: 25% كحد أقصى، وإطار زمني شهر واحد
الاستخدام الإضافي: مفعّل، وتتم فوترته عند الفوترة
المقياس: ai.generation مع تجميع Sum في حقل tokens

API Gateway

هيكل التسعير:

الخطة	السعر	الاعتمادات/الشهر	الاستخدام الإضافي
Free	$0/mo	1,000 استدعاء	محظور
Developer	$19/mo	50,000 استدعاء	$0.001/استدعاء
Business	$99/mo	500,000 استدعاء	$0.0005/استدعاء

الإعداد:

نوع الاعتماد: Custom Unit (“API Calls”)
الدقة: 0 (استدعاءات كاملة)
الترحيل: معطّل
الاستخدام الإضافي: تسمح خطط Developer+ بالاستخدام الإضافي (الإعفاء عند إعادة الضبط)، بينما تعطّله خطة Free
المقياس: api.request مع تجميع Count

Cloud Storage Service

هيكل التسعير:

الخطة	السعر	الاعتمادات/الشهر	الاستخدام الإضافي
Personal	$9/mo	100 GB-hour	$0.05/GB-hour
Team	$49/mo	1,000 GB-hour	$0.03/GB-hour

الإعدادات:

نوع الرصيد: وحدة مخصصة (“GB-hours”)
الدقة: 2 (منزلتان عشريتان)
الترحيل: بحد أقصى 50%، يُرحَّل مرة واحدة
التجاوز: مفعّل، مع تحديد حد للتجاوز بوحدة GB-hours
العداد: storage.usage مع تجميع Sum

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

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

يعمل Credit-Based Billing مع جميع ميزات Dodo Payments الأخرى: الاشتراكات مع التجارب، وتغييرات الخطط مع التوزيع النسبي، وCustomer Portal. ابدأ بإعداد أساسي ثم وسّعه مع تطور نموذج التسعير لديك.

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

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

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

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

​مصادر المنح

​إنشاء أرصدة

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

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

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

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

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

​الترحيل

​التجاوز

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

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

​كيفية عمل خصم الاعتمادات المستند إلى المقاييس

​لوحة المقاييس

​تجربة العميل

​صفحة الدفع

​Customer Portal

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

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

​إدارة الاعتمادات

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

​قائمة استحقاقات الاعتمادات

​تفاصيل اعتمادات العميل

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

​دفتر أستاذ الاعتمادات

​Webhooks

Credit Webhook Payloads

​إدارة API

Create Credit Entitlement

List Credit Entitlements

Get Credit Entitlement

Update Credit Entitlement

Delete Credit Entitlement

Undelete Credit Entitlement

Create Ledger Entry

List Balances

Get Customer Balance

List Customer Grants

List Customer Ledger

​مثال على التكامل

​أمثلة من العالم الحقيقي

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

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

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

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

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

مصادر المنح

إنشاء أرصدة

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

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

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

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

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

الترحيل

التجاوز

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

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

كيفية عمل خصم الاعتمادات المستند إلى المقاييس

لوحة المقاييس

تجربة العميل

صفحة الدفع

Customer Portal

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

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

إدارة الاعتمادات

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

قائمة استحقاقات الاعتمادات

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

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

دفتر أستاذ الاعتمادات

Webhooks

إدارة API

مثال على التكامل

أمثلة من العالم الحقيقي

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