إنتقل إلى المحتوى الرئيسي

الفترات التجريبية

يمكن أن تتضمن الاشتراكات فترة تجريبية لا يلزم خلالها أي دفع. عند انتهاء الفترة التجريبية تبدأ أول دورة فوترة ويُخصم من الدافع (أو يُرسل إليه رابط دفع) وفق collection_method.

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

  • trial_period_days — يُضبط عند الإنشاء؛ ويبدأ الاشتراك بحالة trialing. لا تُحصَّل أي دفعة خلال عدد الأيام المحدد منذ الإنشاء.
  • trial_end — طابع زمني ISO اختياري لتحديد نهاية صريحة للفترة التجريبية. ويمكنك أيضًا ضبط trial_end: "now" للبدء فعليًا دون فترة تجريبية.
  • عند انتهاء الفترة التجريبية:
    • إذا كانت collection_method هي send_payment_link: يُنشأ رابط دفع للفترة الأولى و(إن كان مضبوطًا) يُراسَل الدافع بالبريد.
    • إذا كانت collection_method هي auto_charge: يجب أن يكون الدافع قد وافق على الـ allowance قبل انتهاء الفترة التجريبية أو عنده؛ وإلا فقد ينتقل الاشتراك إلى paused حتى يوافق.
  • subscription.trial_will_end — ترسل OrcaRail هذا الـ webhook قبل نحو 3 أيام من trial_end لتتمكن من تذكير الدافع بإضافة طريقة دفع أو الموافقة على الخصم التلقائي.

إنشاء اشتراك بفترة تجريبية​

استخدم trial_period_days (أو trial_end) عند إنشاء الاشتراك:

POST /api/v1/subscriptions
{
  "description": "Pro Plan",
  "amount": "10.00",
  "currency": "usd",
  "token_id": "...",
  "network_id": "...",
  "interval": "month",
  "trial_period_days": 14,
  "payer_email": "[email protected]"
}

ستتضمن الاستجابة:

  • status: "trialing"
  • trial_start: وقت الإنشاء
  • trial_end: وقت الإنشاء + 14 يومًا
  • current_period_start / current_period_end: أول فترة فوترة بعد الفترة التجريبية

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

يمكنك تحديث trial_end لاشتراك قائم (مثلًا لتمديد الفترة التجريبية أو تقصيرها):

PATCH /api/v1/subscriptions/:id
{
  "trial_end": "2025-04-15T00:00:00Z"
}

استخدم "now" لإنهاء الفترة التجريبية فورًا وبدء أول دورة فوترة.

تدفق الحالات مع الفترات التجريبية​

  • trialing — لا خصم بعد؛ وtrial_end في المستقبل.
  • بعد trial_end: ينتقل الاشتراك إلى active بمجرد دفع الفترة الأولى (أو إلى paused إن لم توجد طريقة دفع / allowance).

الـ webhooks​

  • subscription.created — يُرسل عند إنشاء الاشتراك (قد يكون trialing).
  • subscription.trial_will_end — يُرسل قبل نحو 3 أيام من trial_end؛ استخدمه لمراسلة الدافع أو حثّه على الموافقة على الخصم التلقائي.
  • subscription.payment_link.created — عند إنشاء أول رابط دفع بعد الفترة التجريبية (في send_payment_link).
  • subscription.payment_link.paid — عند دفع أول دورة بعد الفترة التجريبية.

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

  1. ذكّر قبل انتهاء الفترة التجريبية — عالِج subscription.trial_will_end لإرسال بريد أو رسالة داخل التطبيق.
  2. الخصم التلقائي والفترات التجريبية — في auto_charge، وجّه الدافع للموافقة على الـ allowance قبل trial_end لينجح الخصم الأول؛ وإلا فقد يصبح الاشتراك paused أو past_due.
  3. رسائل واضحة — اعرض في صفحة الدفع أو الاشتراك مدة الفترة التجريبية وتاريخ الخصم الأول ومبلغه ليعرف الدافع ما يتوقعه.

الخطوات التالية​