> ## 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.

# الخصومات

> أنشئ رموز ترويجية لتحفيز التحويلات، وتشغيل الحملات، ومكافأة العملاء بخصومات نسبة مئوية عبر المشتريات الفردية والاشتراكات.

<Frame>
  <img src="https://mintcdn.com/dodopayments/mOQO5ej_lx0yH9p-/images/discount-codes/discount-code-cover.png?fit=max&auto=format&n=mOQO5ej_lx0yH9p-&q=85&s=57f1a644801ddc5efc506b50541eaaba" alt="واجهة نظرة عامة على أكواد الخصم" style={{ maxHeight: '500px', width: 'auto' }} width="1200" height="630" data-path="images/discount-codes/discount-code-cover.png" />
</Frame>

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

<CardGroup cols={2}>
  <Card title="Checkout Sessions" icon="cart-shopping" href="/developer-resources/checkout-session">
    قم بتطبيق الرموز أثناء إتمام الدفع المستضاف باستخدام `discount_code` وعناصر التحكم في واجهة المستخدم.
  </Card>

  <Card title="Validate Discount" icon="code" href="/api-reference/discounts/validate-discount">
    تحقق مما إذا كان الخصم صالحًا بواسطة معرفه.
  </Card>

  <Card title="Get Discount by Code" icon="tag" href="/api-reference/discounts/get-discount-by-code">
    ابحث عن الخصم وتأكد من صحته باستخدام اسم الرمز الخاص به (على سبيل المثال، "SAVE20").
  </Card>

  <Card title="Create Discount (API)" icon="code" href="/api-reference/discounts/create-discount">
    أنشئ رموز خصم جديدة برمجيًا.
  </Card>

  <Card title="List & Update Discounts" icon="code" href="/api-reference/discounts/list-discounts">
    تصفح وإدارة الخصومات الحالية؛ قم بالتحديث أو الحذف حسب الحاجة.
  </Card>

  <Card title="Plan Change Discounts" icon="arrows-rotate" href="/api-reference/subscriptions/change-plan">
    تطبيق رموز الخصم عند ترقية أو تخفيض خطط الاشتراك.
  </Card>
</CardGroup>

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

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

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

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

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

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

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

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

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

<Tip>
  استخدم حدود الدورات للتسعير التمهيدي للاشتراكات (مثل "خصم 50% لمدة 3 أشهر").
</Tip>

## تجربة الدفع

1. يدخل المتسوقون الرمز في حقل الدفع.
2. يتم تطبيق الخصومات المؤهلة وتحديث الإجماليات فورًا.

<Info>
  في جلسات الدفع، قم بتمرير `discount_code` لتطبيق رمز مسبقًا، واضبط `feature_flags.allow_discount_code` لعرض حقل الإدخال.
</Info>

## إدارة API

<AccordionGroup>
  <Accordion title="Create discounts">
    أنشئ رموز الخصم برمجيًا مع النوع والمبلغ.

    <Card title="API Reference" icon="code" href="/api-reference/discounts/create-discount">
      عرض إنشاء واجهة برمجة تطبيقات الخصم.
    </Card>
  </Accordion>

  <Accordion title="List and retrieve">
    قائمة جميع الخصومات أو استرداد التفاصيل للإدارة والمراجعة.

    <Card title="API Reference" icon="code" href="/api-reference/discounts/list-discounts">
      تصفح قائمة APIs والاسترداد.
    </Card>
  </Accordion>

  <Accordion title="Get discount by code">
    ابحث عن خصم باستخدام رمزه القابل للقراءة البشري (مثل "SAVE20") بدلاً من المعرف الداخلي.

    <Card title="API Reference" icon="code" href="/api-reference/discounts/get-discount-by-code">
      استرداد الخصم بالاسم الرمز.
    </Card>
  </Accordion>

  <Accordion title="Update discounts">
    تعديل تكوين الخصم مثل المبلغ أو الانتهاء أو القيود.

    <Card title="API Reference" icon="code" href="/api-reference/discounts/update-discount">
      تعلم كيفية تحديث تفاصيل الخصم.
    </Card>
  </Accordion>

  <Accordion title="Validate discounts">
    تحقق مما إذا كان الخصم صالحًا وقابل للتطبيق قبل التطبيق.

    <Card title="API Reference" icon="code" href="/api-reference/discounts/validate-discount">
      تحقق من استخدام الخصم.
    </Card>
  </Accordion>

  <Accordion title="Delete discounts">
    إلغاء التفعيل أو إزالة الخصومات التي لم تعد بحاجة إليها.

    <Card title="API Reference" icon="code" href="/api-reference/discounts/delete-discount">
      حذف خصم.
    </Card>
  </Accordion>
</AccordionGroup>

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

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

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

### إنشاء خصم مع البيانات الوصفية

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

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

<Tip>
  استخدم البيانات الوصفية لتمييز الخصومات حسب الحملة أو المصدر أو معرّف المرجع الداخلي لتتمكن من تسوية الاستخدام وقياس عائد الاستثمار لاحقًا.
</Tip>

### تطبيق خصم في جلسات الدفع

تقديم خصم مسبق وعرض واجهة إدخال الرمز.

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'prod_abc', quantity: 1 }
  ],
  discount_code: 'BLACKFRIDAY2024',
  customer: { email: 'user@example.com', name: 'Jane Doe' },
  return_url: 'https://yoursite.com/return'
});
```

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

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

```typescript theme={null}
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_code: 'UPGRADE20'
});
```

<Info>
  إذا كانت الاشتراك بالفعل يحتوي على خصم برمز `preserve_on_plan_change=true` ولم تقم بتمرير رمز جديد، يتم الحفاظ تلقائيًا على الخصم الحالي عندما ينطبق على المنتج الجديد.
</Info>

### تفعيل إدخال الخصم بدون تطبيق مسبق

اسمح للعملاء بإدخال رمز عند الدفع بدون تمرير رمز مسبق.

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'prod_abc', quantity: 1 }
  ],
  feature_flags: {
    allow_discount_code: true
  },
  return_url: 'https://yoursite.com/return'
});
```

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

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

<Info>
  أكواد الخصم هي عناصر قوية للاكتساب والاحتفاظ. ابدأ بعروض بسيطة وذات أسماء واضحة، تحقق بدقة، وكرر العملية بناءً على الأداء.
</Info>

### تمكين إدخال الخصم دون التطبيق المسبق

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

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'prod_abc', quantity: 1 }
  ],
  feature_flags: {
    allow_discount_code: true
  },
  return_url: 'https://yoursite.com/return'
});
```

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

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

<Info>
  أكواد الخصم أدوات قوية للاستحواذ والاحتفاظ. ابدأ بعروض بسيطة وسهل الفهم، تحقق بدقة، وكرر بناءً على الأداء.
</Info>