קופונים

צור קודי הנחה שלקוחות יכולים להחיל בקופה. אחוז או סכום קבוע, מוגבל בזמן או בכמות, חד-פעמי או חוזר.

קופונים מנוהלים בלשונית המשנה Commerce panel > 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',
});

העברת קוד קופון באופן פרוגרמטי בקריאת ה-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. קופונים שנוצרו ב-builder Dashboard אינם גלויים דרך coupons.list().

הערות ומגבלות

• קודים וסכומי הנחה הם בלתי-ניתנים לשינוי. ניתן לעדכן את שם התצוגה name ולהחליף את מצב active, אך לא את percent_off, amount_off או את code עצמו. צור קופון חדש אם אתה זקוק לתנאים שונים.
• times_redeemed מתעדכן אוטומטית ולקריאה בלבד — שימושי למעקב אחר ביצועי קמפיין.
• קופונים מוחלים לפי לקוח, לא לפי הזמנה — אם קופון הוא forever ולקוח נרשם למנוי, כל חידוש מקבל את ההנחה.