الخصومات

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

Checkout Sessions

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

Validate Discount

تحقق مما إذا كان الخصم صالحًا بواسطة معرفه.

Get Discount by Code

ابحث عن الخصم وتأكد من صحته باستخدام اسم الرمز الخاص به (على سبيل المثال، “SAVE20”).

Create Discount (API)

أنشئ رموز خصم جديدة برمجيًا.

List & Update Discounts

تصفح وإدارة الخصومات الحالية؛ قم بالتحديث أو الحذف حسب الحاجة.

Plan Change Discounts

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

ما هي رموز الخصم؟

رموز الخصم هي رموز ترويجية تقلل من الإجمالي عند الدفع. إنها مثالية لـ:

الحملات الموسمية: الجمعة السوداء، إطلاق المنتجات، أو الذكريات السنوية
عروض الاستحواذ: حوافز الشراء الأول أو مكافآت الإحالة
الحفاظ على العملاء: مكافآت الاستعادة أو الولاء للعملاء الحاليين
صفقات B2B: التسعير المتفق عليه أو المتفاوض عليه عبر رموز خاصة

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

خصومات مرنة: خصومات تستند إلى نسبة مئوية أو مبلغ ثابت
رموز قابلة للتجميع: طبّق ما يصل إلى 20 رمزًا لكل عملية إتمام شراء أو دفعة أو اشتراك — ادمج الحملات (مثل WELCOME10 + BLACKFRIDAY20) من دون إنشاء رموز مخصصة
تحكم موجّه: قيّد الاستخدام حسب المنتج ودورات الاشتراك وأهلية العميل
حوكمة الحملات: تواريخ بدء مجدولة، وتواريخ انتهاء، وحدود استخدام إجمالية ولكل عميل
تسعير حسب العملة: حدّد الخصم الثابت وسقف المبلغ والحد الأدنى للإجمالي الفرعي لكل عملة
إتمام شراء سلس: دعم حقل واجهة المستخدم وAPI عبر جلسات إتمام الشراء

إنشاء رموز الخصم

أنشئ رموز الخصم في لوحة التحكم في Dodo Payments، ثم قم بتطبيقها في الدفع المستضاف أو عبر API.

قائمة الخصومات في لوحة تحكم Dodo Payments تعرض رموز الخصم الحالية

إعداد لوحة التحكم

اسم الخصم (مطلوب): الاسم الداخلي والاسم المعروض في لوحة التحكم
الرمز (مطلوب): السلسلة التي يُدخلها العملاء عند إتمام الشراء، أو أنشئ رمزًا عشوائيًا باستخدام الزر المتوفر
النوع (مطلوب): اختر النسبة المئوية (خصم بنسبة مئوية) أو المبلغ (خصم ثابت)
المبلغ (مطلوب): قيمة النسبة المئوية أو المبلغ الثابت لخصم من نوع المبلغ
تاريخ البدء (اختياري): جدولة تفعيل الرمز لاحقًا؛ اتركه فارغًا لتفعيله فورًا
تاريخ الانتهاء (اختياري): التاريخ الذي يصبح الرمز بعده غير صالح
حد الاستخدام (اختياري): الحد الأقصى لعدد عمليات الاسترداد لدى جميع العملاء
حد الاستخدام لكل عميل (اختياري): الحد الأقصى لعدد عمليات الاسترداد لأي عميل واحد. يجب أن يكون أقل من أو مساويًا لحد الاستخدام الإجمالي عند تحديد كليهما
أهلية العميل (اختياري): قيّد من يمكنه استرداد الرمز — جميع العملاء أو العملاء لأول مرة أو العملاء الحاليون أو قائمة محددة يدويًا
خيارات العملة (اختياري): قيم لكل عملة — راجع خيارات العملة
تقييد المنتج (اختياري): قصِر قابلية التطبيق على منتجات محددة
حد دورة الاشتراك (اختياري): عدد دورات الفوترة التي ينطبق عليها الخصم
الاحتفاظ عند تغيير الخطة (اختياري): أبقِ الخصم فعالًا عند تغيير خطة الاشتراك (preserve_on_plan_change)
البيانات الوصفية (اختياري): أرفق أزواجًا مخصصة من المفاتيح والقيم للتتبع الداخلي أو عمليات التكامل

تفاصيل الخصم — النوع والنسبة المئوية أو المبلغ والاسم والرمز وخيارات العملة:

نموذج رمز خصم جديد يعرض النوع ومبلغ النسبة المئوية والاسم والرمز وخيارات العملة

حدود الاستخدام والانتهاء، بعد إعدادها بالكامل:

لوحة حدود الاستخدام والانتهاء مع إعداد تاريخ البدء وتاريخ الانتهاء وحدود الاستخدام

في الجزء السفلي من النموذج — الأهلية والقيود والخيارات المتقدمة:

الأهلية والقيود والخيارات المتقدمة لرمز الخصم

استخدم حدود الدورات للتسعير التمهيدي على الاشتراكات (مثل “خصم 50% لمدة 3 أشهر”).

يُعبَّر عن amount المئوي بوحدات نقاط الأساس عبر API — 1500 تعني 15%. أما amount الثابت فهو قيمة مالية وتحدده خيارات عملة الرمز.

أنواع الخصومات

النوع	قيمة API	السلوك
النسبة المئوية	`percentage`	يخفض السعر بنسبة مئوية. ويمكن اختياريًا تحديد سقف له لكل عملة باستخدام حد أقصى للخصم.
المبلغ	`flat`	يخصم مبلغًا ثابتًا. ويُجمّع الخصم على مستوى سلة التسوق بأكملها بدلًا من تطبيقه على كل عنصر.

يمكن دمج كلا النوعين في مصفوفة discount_codes نفسها، ويُطبّقان بترتيب المصفوفة.

محرر رمز الخصم مع تحديد نوع المبلغ، ويعرض خصمًا ثابتًا قدره 500 INR

أهلية العميل

حدّد customer_eligibility للتحكم في من يمكنه استرداد الرمز:

القيمة	من يمكنه الاسترداد
`any`	أي عميل. وهذا هو الإعداد الافتراضي.
`first_time`	العملاء الذين لم يشتروا منك من قبل.
`existing`	العملاء الذين اشتروا منك من قبل.
`specific`	العملاء الذين تضيفهم فقط إلى قائمة السماح الخاصة بالرمز.

قائمة أهلية العميل المنسدلة التي تعرض خيارات أي عميل والعملاء لأول مرة والعملاء الحاليين وعميل محدد

يبدأ رمز specific مع صفر من العملاء المؤهلين، ويرفض كل عملية استرداد إلى أن تضيف العملاء إليه. أضفهم من لوحة التحكم أو باستخدام API عملاء الخصم.

اربط الأهلية مع حد الاستخدام لكل عميل لتحديد عدد مرات استرداد كل عميل للرمز بشكل مستقل عن حد الاستخدام الإجمالي.

خيارات العملة

تتيح خيارات العملة لرمز واحد العمل بشكل صحيح عبر العملات التي تبيع بها. يحدد كل إدخال، لعملة واحدة:

المبلغ — بالنسبة إلى خصم من نوع المبلغ، يكون هذا هو الخصم نفسه؛ وبالنسبة إلى خصم من نوع النسبة المئوية، يحدد الحد الأقصى الذي يمكن للرمز خصمه. ويُطابق max_amount_possible عبر API.
الإجمالي الفرعي الأدنى — لا ينطبق الرمز إلا عندما تصل السلة إلى هذا الإجمالي الفرعي. ويعني 0 عدم وجود حد أدنى.
الافتراضي — يمكن تحديد إدخال واحد كافتراضي لتحويل العملات الأخرى غير المُهيّأة منه.

لوحة خيارات العملة مع مبلغ لكل عملة وإجمالي فرعي أدنى لعملتي INR وUSD

يتطلب خصم من نوع المبلغ خيار عملة واحدًا على الأقل مع قيمة افتراضية قابلة للتحديد، إذ لا معنى لخصم ثابت من دون عملة. أما خيارات العملة فهي اختيارية لخصومات النسبة المئوية.

يُقاس الحد الأدنى للإجمالي الفرعي دائمًا مقابل الأسعار الأصلية للسلع في السلة، وليس مقابل الإجمالي الجاري في منتصف عملية التجميع. لذلك لا يغيّر ترتيب التجميع ما إذا كان الحد الأدنى مستوفى أم لا.

تجربة إتمام الشراء

يُدخل المتسوقون الرمز في حقل إتمام الشراء.
تُطبّق الخصومات المؤهلة وتُحدّث الإجماليات فورًا.

صفحة إتمام الشراء تعرض خصمًا مطبقًا على إجمالي الطلب

في Checkout Sessions، مرّر discount_codes (وهي مصفوفة) لتطبيق رمز واحد أو أكثر مسبقًا. يظهر حقل إدخال الخصم افتراضيًا — إذ إن feature_flags.allow_discount_code تكون قيمته الافتراضية true، لذا اضبطه على false فقط إذا كنت تريد إخفاءه. تُطبَّق الرموز بترتيبها في المصفوفة، وبحد أقصى 20 رمزًا.

تجميع رموز الخصم

تقبل جلسات إتمام الشراء والمدفوعات والاشتراكات ما يصل إلى 20 رمزًا مجمعًا عبر مصفوفة discount_codes (بحد أقصى 20 إدخالًا). تُطبّق الرموز بترتيب المصفوفة، إذ يخفض الرمز المؤهل الأول السعر الأساسي أولًا، ثم يخفض الرمز التالي السعر بعد الخصم، وهكذا. تُعاد مجموعة الخصومات المطبقة كاملةً في الاستجابة ضمن discount_ids (في المدفوعات/الاشتراكات) وdiscounts (تفاصيل أغنى لكل خصم، بما في ذلك الموضع ودورات الاشتراك المتبقية).

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  discount_codes: ['WELCOME10', 'BLACKFRIDAY20'], // applied in this order
  customer: { email: 'user@example.com' },
  return_url: 'https://yoursite.com/return'
});

حقل discount_code المفرد مهمل لكنه لا يزال مدعومًا بالكامل للتوافق مع الإصدارات السابقة — وستستمر عمليات التكامل الحالية في العمل دون تغييرات. ولا يمكن دمجه مع discount_codes في الطلب نفسه. نوصي بالترحيل إلى discount_codes (صيغة المصفوفة) عندما يكون ذلك مناسبًا، حتى مع الرموز المفردة، للاستفادة من التجميع وبنية الاستجابة الأكثر تفصيلًا.

إدارة API

Create discounts

أنشئ رموز الخصم برمجيًا مع تحديد النوع والمبلغ.

API Reference

اطّلع على API إنشاء الخصم.

List and retrieve

اعرض جميع الخصومات أو استرجع تفاصيلها لأغراض الإدارة والتدقيق.

API Reference

تصفّح APIs الخاصة بالقوائم والاسترجاع.

Get discount by code

ابحث عن خصم باستخدام رمزه المقروء بشريًا (مثل “SAVE20”) بدلًا من المعرّف الداخلي.

API Reference

استرجع الخصم حسب اسم الرمز.

Update discounts

عدّل إعدادات الخصم، مثل المبلغ أو تاريخ الانتهاء أو القيود.

API Reference

تعرّف على كيفية تحديث تفاصيل الخصم.

Validate discounts

تحقق مما إذا كان الخصم صالحًا وقابلًا للتطبيق قبل تطبيقه.

API Reference

تحقق من استخدام الخصم.

Delete discounts

عطّل الخصومات أو احذفها عندما لا تعود مطلوبة.

API Reference

احذف خصمًا.

Manage the customer allow list

بالنسبة إلى خصم تم ضبط customer_eligibility فيه على specific، أدر العملاء الذين يمكنهم استرداده:

GET /discounts/{discount_id}/customers — اعرض قائمة العملاء المرفقين (مقسّمة إلى صفحات، بحد أقصى 100 عميل لكل صفحة).
POST /discounts/{discount_id}/customers — أرفق العملاء حسب المعرّف. العملية متكررة بشكل آمن (idempotent) وتقبل ما يصل إلى 1000 معرّف، ويجب أن تكون جميعها موجودة مسبقًا في نشاطك التجاري. تعكس الاستجابة المعرّفات المرسلة في ذلك الطلب فقط، لذا استخدم نقطة النهاية الخاصة بالقائمة لقراءة قائمة السماح كاملة.
DELETE /discounts/{discount_id}/customers/{customer_id} — افصل عميلًا واحدًا.

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

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

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

إنشاء خصم باستخدام البيانات الوصفية

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

const discount = await client.discounts.create({
  type: 'percentage',
  amount: 1500, // 15%
  code: 'SUMMER2025',
  metadata: {
    campaign: 'summer_promo',
    source: 'email_blast'
  }
});

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

تطبيق الخصومات في جلسات إتمام الشراء

طبّق خصمًا واحدًا أو أكثر من الخصومات المجمعة مسبقًا، وأظهر واجهة إدخال الرمز.

const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_abc', quantity: 1 }
  ],
  discount_codes: ['BLACKFRIDAY2024', 'NEWUSER5'], // stacked in array order
  customer: { email: 'user@example.com', name: 'Jane Doe' },
  return_url: 'https://yoursite.com/return'
});

تطبيق الخصومات أثناء تغيير الخطة

قدّم أسعارًا ترويجية عند ترقية العملاء لاشتراكاتهم أو خفضها.

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_codes: ['UPGRADE20']
});

قيمة `discount_codes`	السلوك عند تغيير الخطة
`undefined` / `null` (غير مقدمة)	يُحتفظ بالخصومات الحالية التي تحتوي على `preserve_on_plan_change=true` إذا كانت قابلة للتطبيق على المنتج الجديد.
`[]` (مصفوفة فارغة)	تُزال جميع الخصومات الحالية من الاشتراك.
`['CODE_A', 'CODE_B', ...]`	يستبدل أي خصومات حالية بهذه المجموعة المجمعة، وتُطبّق بترتيب المصفوفة.

اقرأ جميع الخصومات المطبقة من الاشتراك عبر مصفوفة discounts الجديدة في استجابة الاشتراك. يتضمن كل إدخال discount_id وposition وcycles_remaining (للاشتراكات) والرمز الأصلي.

إخفاء حقل رمز الخصم

يظهر حقل إدخال الخصم افتراضيًا، لذا يمكن للعملاء إدخال رمز في أي وقت من دون أن تمرّر رمزًا مسبقًا. اضبط allow_discount_code على false لإخفاء الحقل بالكامل.

const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_abc', quantity: 1 }
  ],
  feature_flags: {
    allow_discount_code: false
  },
  return_url: 'https://yoursite.com/return'
});

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

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

رموز الخصم أدوات مؤثرة لاكتساب العملاء والاحتفاظ بهم. ابدأ بعروض بسيطة ذات أسماء واضحة، وتحقق منها بدقة، ثم حسّنها استنادًا إلى الأداء.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions

Validate Discount

Get Discount by Code

Create Discount (API)

List & Update Discounts

Plan Change Discounts

ما هي رموز الخصم؟

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

إنشاء رموز الخصم

إعداد لوحة التحكم

أنواع الخصومات

أهلية العميل

خيارات العملة

تجربة إتمام الشراء

تجميع رموز الخصم

إدارة API

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

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

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

إنشاء خصم باستخدام البيانات الوصفية

تطبيق الخصومات في جلسات إتمام الشراء

تطبيق الخصومات أثناء تغيير الخطة

إخفاء حقل رمز الخصم

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

Checkout Sessions

Validate Discount

Get Discount by Code

Create Discount (API)

List & Update Discounts

Plan Change Discounts

​ما هي رموز الخصم؟

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

​إنشاء رموز الخصم

​إعداد لوحة التحكم

​أنواع الخصومات

​أهلية العميل

​خيارات العملة

​تجربة إتمام الشراء

​تجميع رموز الخصم

​إدارة API

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

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

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

​إنشاء خصم باستخدام البيانات الوصفية

​تطبيق الخصومات في جلسات إتمام الشراء

​تطبيق الخصومات أثناء تغيير الخطة

​إخفاء حقل رمز الخصم

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

ما هي رموز الخصم؟

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

إنشاء رموز الخصم

إعداد لوحة التحكم

أنواع الخصومات

أهلية العميل

خيارات العملة

تجربة إتمام الشراء

تجميع رموز الخصم

إدارة API

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

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

إنشاء خصم باستخدام البيانات الوصفية

تطبيق الخصومات في جلسات إتمام الشراء

تطبيق الخصومات أثناء تغيير الخطة

إخفاء حقل رمز الخصم

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