القسائم

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

تُدار القسائم من خلال لوحة Commerce > Products > Coupons في Builder، أو عبر SDK على المسار proyecta.commerce.coupons.

مكونات القسيمة

الحقل	ملاحظات
code	كود العرض الترويجي الذي يكتبه العملاء عند الدفع (مثال: LAUNCH20)
percent_off أو amount_off	لا يمكن استخدامهما معاً. النسبة المئوية تتراوح بين 1 و100. المبلغ يُحدَّد بأصغر وحدة للعملة (السنتات).
currency	مطلوب لخصومات amount_off (رمز ISO من ثلاثة أحرف). يُقبَل عند الإنشاء ويُرسَل إلى Stripe، لكنه لا يُخزَّن ولا تُعيده الـ API بعد ذلك.
duration	once (الدفعة الأولى فقط)، أو repeating (لـ duration_in_months)، أو forever
duration_in_months	مطلوب عندما تكون duration بقيمة repeating
max_redemptions	الحد الأقصى الإجمالي لعمليات الاسترداد عبر جميع العملاء
redeem_by	تاريخ انتهاء الصلاحية الذي تتوقف القسيمة عن العمل بعده
name	الاسم الظاهر للعملاء
active	زر تبديل لتفعيل القسيمة أو تعطيلها دون حذفها

إنشاء قسيمة

من تبويب Coupons، انقر على Add coupon وأكمل الحقول المطلوبة. أو عبر SDK:

// 20% off forever
await proyecta.commerce.coupons.create({
    code: 'LAUNCH20',
    name: 'Launch discount',
    percent_off: 20,
    duration: 'forever',
});

// $10 off, single use, expires in 30 days
await proyecta.commerce.coupons.create({
    code: 'WELCOME10',
    amount_off: 1000,
    currency: 'USD',
    duration: 'once',
    max_redemptions: 1,
    redeem_by: new Date(Date.now() + 30 * 86400 * 1000).toISOString(),
});

// 50% off for the first 3 months of a subscription
await proyecta.commerce.coupons.create({
    code: 'EARLY3',
    percent_off: 50,
    duration: 'repeating',
    duration_in_months: 3,
});

تطبيق قسيمة عند الدفع

يستطيع العملاء إدخال كود القسيمة بأنفسهم في صفحة الدفع المستضافة على Stripe — يظهر حقل الكود الترويجي تلقائياً.

await proyecta.commerce.checkout({
    customer_id,
    line_items: [{ variant_id: 'var_pro_monthly' }],
    success_url: 'https://myapp.com/welcome',
});

تمرير كود القسيمة برمجياً في طلب الدفع غير مدعوم حتى الآن.

عرض القسائم وتحديثها وتعطيلها

// Browse every coupon (only lists coupons created via the SDK)
const { data } = await proyecta.commerce.coupons.list();
for (const coupon of data.data) {
    console.log(coupon.code, coupon.times_redeemed, '/', coupon.max_redemptions);
}
// Paginate using data.has_more and the starting_after query parameter if needed.

// Disable a coupon (without deleting)
await proyecta.commerce.coupons.update({ couponId: 'coupon_123', active: false });

ملاحظة: تُرجع coupons.list() فقط القسائم التي أُنشئت عبر SDK. القسائم التي أُنشئت من لوحة Builder غير مرئية من خلال coupons.list().

ملاحظات وقيود

• الأكواد ومبالغ الخصم غير قابلة للتعديل. يمكنك تحديث name وتبديل active، لكن لا يمكن تغيير percent_off أو amount_off أو code نفسه. أنشئ قسيمة جديدة إذا احتجت إلى شروط مختلفة.
• times_redeemed يتزايد تلقائياً وهو للقراءة فقط — مفيد لتتبع أداء الحملات الترويجية.
• تُطبَّق القسائم لكل عميل، لا لكل طلب — فإذا كانت القسيمة forever واشترك العميل، فسيحصل على الخصم في كل عملية تجديد.