کوپن‌ها

کدهای تخفیف بسازید که مشتریان می‌توانند هنگام پرداخت وارد کنند. درصدی یا مبلغ ثابت، با محدودیت زمانی یا سقف استفاده، یک‌بار یا تکرارشونده.

کوپن‌ها در پنل Commerce > Products > Coupons در builder مدیریت می‌شوند، یا از طریق SDK در proyecta.commerce.coupons.

ساختار یک کوپن

فیلد	توضیحات
code	کد تبلیغاتی که مشتریان هنگام پرداخت وارد می‌کنند (مثلاً LAUNCH20)
percent_off یا amount_off	این دو با هم قابل استفاده نیستند. درصد باید بین ۱ تا ۱۰۰ باشد. مبلغ بر اساس کوچک‌ترین واحد ارز (سنت) است.
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,
});

اعمال کوپن هنگام پرداخت

مشتریان می‌توانند کد کوپن را خودشان در صفحه checkout میزبانی‌شده توسط Stripe وارد کنند — فیلد کد تبلیغاتی به‌صورت خودکار نمایش داده می‌شود.

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

ارسال برنامه‌نویسی کد کوپن در فراخوانی checkout هنوز پشتیبانی نمی‌شود.

فهرست، به‌روزرسانی، غیرفعال‌سازی

// 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 ساخته شده‌اند برمی‌گرداند. کوپن‌هایی که در Dashboard سازنده ایجاد شده‌اند از طریق coupons.list() قابل مشاهده نیستند.

نکات و محدودیت‌ها

• کدها و مبالغ تخفیف قابل تغییر نیستند. می‌توانید name نمایشی را ویرایش کنید و active را تغییر دهید، اما percent_off، amount_off یا خود code را نمی‌توانید تغییر دهید. اگر به شرایط متفاوتی نیاز دارید، یک کوپن جدید بسازید.
• times_redeemed به‌صورت خودکار افزایش می‌یابد و فقط خواندنی است — برای پیگیری عملکرد کمپین مفید است.
• کوپن‌ها به ازای هر مشتری اعمال می‌شوند، نه به ازای هر سفارش — اگر کوپنی forever باشد و مشتری اشتراک بگیرد، هر تمدید نیز تخفیف را دریافت می‌کند.