الاشتراكات

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.

​

ما هي الاشتراكات؟

• ترخيص SaaS: التطبيقات، واجهات برمجة التطبيقات، أو الوصول إلى المنصات
• العضويات: المجتمعات، البرامج، أو الأندية
• المحتوى الرقمي: الدورات، الوسائط، أو المحتوى المتميز
• خطط الدعم: اتفاقيات مستوى الخدمة، حزم النجاح، أو الصيانة

​

الفوائد الرئيسية

• إيرادات متوقعة: فواتير متكررة مع تجديدات تلقائية
• دورات مرنة: شهرية، سنوية، فترات مخصصة، وتجارب
• مرونة الخطط: تقسيط للترقيات والتخفيضات
• إضافات ومقاعد: أضف ترقيات اختيارية وقابلة للقياس
• تجربة دفع سلسة: دفع مستضاف وبوابة العملاء
• موجه للمطورين: واجهات برمجة تطبيقات واضحة لإنشاء، تغييرات، وتتبع الاستخدام

​

إنشاء الاشتراكات

​

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

​

تفاصيل المنتج

• اسم المنتج (مطلوب): الاسم المعروض في الدفع، بوابة العملاء، والفواتير.
• وصف المنتج (مطلوب): بيان قيمة واضح يظهر في الدفع والفواتير.
• صورة المنتج (مطلوب): PNG/JPG/WebP حتى 3 ميغابايت. تستخدم في الدفع والفواتير.
• العلامة التجارية: ربط المنتج بعلامة تجارية معينة للتصميم والبريد الإلكتروني.
• فئة الضريبة (مطلوب): اختر الفئة (على سبيل المثال، SaaS) لتحديد قواعد الضريبة.

​

التسعير

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

​

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

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

​

تجارب الاشتراك

​

تكوين التجارب

// Via subscription creation
const subscription = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_monthly',
  trial_period_days: 14  // Overrides product's trial period
});

// Via checkout session
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_monthly', quantity: 1 }],
  subscription_data: { trial_period_days: 14 }
});

​

اكتشاف حالة التجربة

const subscription = await client.subscriptions.retrieve('sub_123');
const payments = await client.payments.list({
  subscription_id: subscription.subscription_id
});

// Check if subscription is in trial
const isInTrial = payments.items.length === 1 && 
                  payments.items[0].total_amount === 0;

​

تحديث فترة التجربة

await client.subscriptions.update('sub_123', {
  next_billing_date: '2025-02-15T00:00:00Z'  // New trial end date
});

​

تغييرات خطة الاشتراك

​

أوضاع النسبة

​

prorated_immediately

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

​

difference_immediately

// Upgrade: charges $50 (difference between $30 and $80)
// Downgrade: credits remaining value, auto-applied to renewals
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

​

full_immediately

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_monthly',
  quantity: 1,
  proration_billing_mode: 'full_immediately'
});

​

do_not_bill

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_new_plan',
  quantity: 1,
  proration_billing_mode: 'do_not_bill'
});

Unused credit from Basic = $30 × (15 remaining / 30 total) = $15.00
Prorated cost of Pro     = $80 × (15 remaining / 30 total) = $40.00
────────────────────────────────────────────────────────────────────
Immediate charge         = $40.00 − $15.00 = $25.00

Credit = Old plan − New plan = $80 − $20 = $60.00

​

تغيير الخطط مع الإضافات

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [{ addon_id: 'addon_extra_seats', quantity: 2 }]  // Add add-ons
  // addons: []  // Empty array removes all existing add-ons
});

​

معاينة تغييرات الخطة

const preview = await client.subscriptions.previewChangePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

// Show customer the charge before confirming
console.log('You will be charged:', preview.immediate_charge.summary);

​

حالات الاشتراك

• active: الاشتراك نشط وسيتجدد تلقائيًا
• on_hold: الاشتراك متوقف بسبب فشل الدفع. تحديث طريقة الدفع مطلوب لتفعيلها من جديد
• cancelled: تم إلغاء الاشتراك ولن يتم تجديده
• expired: وصل الاشتراك إلى تاريخ نهايته
• pending: يجري إنشاء الاشتراك أو معالجته

​

حالة الانتظار

• يفشل الدفع في التجديد (رصيد غير كافٍ، بطاقة منتهية، إلخ.)
• يفشل تحميل تغيير الخطة
• يفشل ترخيص طريقة الدفع

​

إعادة التفعيل من الانتظار

1. بإنشاء تحميل للمبالغ المستحقة
2. توليد فاتورة
3. معالجة الدفع باستخدام طريقة الدفع الجديدة
4. إعادة تفعيل الاشتراك إلى حالة active عند نجاح الدفع

// Reactivate subscription from on_hold
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'new',
  return_url: 'https://example.com/return'
});

// For on_hold subscriptions, a charge is automatically created
if (response.payment_id) {
  console.log('Charge created:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
  // Monitor webhooks for payment.succeeded and subscription.active
}

​

إدارة API

​

حالات الاستخدام الشائعة

• SaaS وAPIs: الوصول المتدرج مع الإضافات للمقاعد أو الاستخدام
• المحتوى والإعلام: الوصول الشهري مع التجارب التمهيدية
• خطط دعم B2B: عقود سنوية مع إضافات دعم متميزة
• الأدوات والمكونات الإضافية: مفاتيح الترخيص والأصدارات المحددة

​

أمثلة التكامل

​

جلسات الخروج (الاشتراكات)

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_subscription',
      quantity: 1
    }
  ]
});

​

تغيير الخطط مع التقسيم

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

​

الإلغاء في تاريخ الفاتورة التالي

await client.subscriptions.update('sub_123', {
  cancel_at_next_billing_date: true
});

​

اشتراكات عند الطلب

const onDemand = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_on_demand',
  on_demand: true
});

await client.subscriptions.createCharge(onDemand.id, {
  amount: 4900,
  currency: 'USD',
  description: 'Extra usage for September'
});

​

تحديث طريقة الدفع للاشتراك النشط

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'new',
  return_url: 'https://example.com/return'
});

// Or use existing payment method
await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'existing',
  payment_method_id: 'pm_abc123'
});

​

إعادة تفعيل الاشتراك من on_hold

// Update payment method - automatically creates charge for remaining dues
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'new',
  return_url: 'https://example.com/return'
});

if (response.payment_id) {
  // Charge created for remaining dues
  // Redirect customer to response.payment_link
  // Monitor webhooks: payment.succeeded → subscription.active
}

​

اشتراكات مع التفويضات المتوافقة مع RBI

​

حدود التفويض

• الرسوم تحت الحد الأدنى للأمر (الافتراضي ₹15,000): نقوم بإنشاء أمر حسب الطلب للمبلغ الأدنى. يتم تحصيل مبلغ الاشتراك دوريًا وفقًا لتكرار اشتراكك، حتى حد الأمر.
• الرسوم عند أو فوق الحد الأدنى للأمر: نقوم بإنشاء أمر اشتراك (أو أمر حسب الطلب) لمبلغ الاشتراك الدقيق.

​

اعتبارات الترقية والتخفيض

• إذا نتج عن الترقية/التخفيض مبلغ رسوم يتجاوز Rs 15,000 ويتخطى حد الدفع الفوري الحالي، فقد يفشل تحصيل العملية.
• في مثل هذه الحالات، قد يحتاج العميل إلى تحديث طريقة الدفع الخاصة به أو تغيير الاشتراك مرة أخرى لإنشاء أمر جديد بالحد الصحيح.

​

التفويض للرسوم مرتفعة القيمة

• سيتم مطالبة العميل من قبل البنك بتفويض المعاملة.
• إذا فشل العميل في تفويض المعاملة، ستفشل المعاملة وسيتم تعليق الاشتراك.

​

تأخير معالجة يستغرق 48 ساعة

• يتم بدء الرسوم في التاريخ المجدول وفقًا لتكرار الاشتراك الخاص بك.
• تحدث الخصم الفعلي من حساب العميل بعد 48 ساعة فقط من بدء الدفع.
• قد تمتد نافذة 48 ساعة هذه حتى 2-3 ساعات إضافية اعتمادًا على استجابات واجهة برمجة التطبيقات للبنك.

​

نافذة إلغاء الأمر

• يمكن للعملاء إلغاء الأمر عبر تطبيقات البنك الخاص بهم.
• إذا قام العميل بإلغاء الأمر خلال هذه الفترة، سيظل الاشتراك نشطًا (هذه حالة خاصة للاشتراكات تلقائية الدفع لبطاقات الهند وUPI).
• ومع ذلك، قد يفشل الخصم الفعلي، وفي هذه الحالة، سنقوم بوضع الاشتراك قيد الانتظار.

• تأخير تفعيل المزايا حتى تأكيد الدفع
• تنفيذ فترات سماح أو وصول مؤقت
• مراقبة حالة الاشتراك لإلغاءات الأوامر
• التعامل مع حالات تعليق الاشتراك في منطق تطبيقك

​

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

• ابدأ بشرائح واضحة: 2-3 خطط بفروقات واضحة
• قم بإبلاغ التسعير: أظهر الإجماليات، النسب، والتجديد التالي
• استخدم التجارب بحكمة: قم بالتحويل باستخدام الإعداد، ليس فقط الوقت
• استفد من الإضافات: اجعل الخطط الأساسية بسيطة وزيادة المبيعات مع الإضافات
• اختبر التغييرات: تحقق من تغييرات الخطة والنسبة في وضع الاختبار