Kuponlar

Müşterilerin ödeme sırasında uygulayabileceği indirim kodları oluşturun. Yüzde veya sabit tutarlı, süreli veya kullanım sınırlı, tek seferlik veya tekrarlayan.

Kuponlar, builder’ın Commerce panel > Products > Coupons alt sekmesinden veya SDK aracılığıyla proyecta.commerce.coupons üzerinden yönetilir.

Kuponun Yapısı

Alan	Notlar
code	Müşterilerin ödeme sırasında gireceği promosyon kodu (örn. LAUNCH20)
percent_off veya amount_off	Birbirini dışlar. Yüzde 1–100 arasındadır. Tutar, en küçük para birimi cinsinden (sent) belirtilir.
currency	amount_off indirimleri için zorunludur (üç harfli ISO kodu). Oluşturma sırasında kabul edilir ve Stripe’a iletilir; ancak sonrasında API tarafından saklanmaz veya döndürülmez.
duration	once (yalnızca ilk ödeme), repeating (duration_in_months için) veya forever
duration_in_months	duration değeri repeating olduğunda zorunludur
max_redemptions	Tüm müşteriler genelinde toplam kullanım sınırı
redeem_by	Kuponun geçerliliğini yitireceği son kullanım tarihi
name	Müşterilere gösterilen görünen ad
active	Silmeden etkinleştirme/devre dışı bırakma için geçiş anahtarı

Kupon Oluşturma

Coupons alt sekmesinden Add coupon seçeneğine tıklayıp alanları doldurun. Ya da SDK ile:

// 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,
});

Ödeme Sırasında Kupon Uygulama

Müşteriler, Stripe tarafından barındırılan ödeme sayfasında kupon kodunu kendileri girebilir — promosyon kodu alanı otomatik olarak görüntülenir.

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

Ödeme çağrısında kupon kodunu programatik olarak iletme henüz desteklenmemektedir.

Listeleme, Güncelleme, Devre Dışı Bırakma

// 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 });

Not: coupons.list() yalnızca SDK aracılığıyla oluşturulan kuponları döndürür. Builder Dashboard’da oluşturulan kuponlar coupons.list() üzerinden görüntülenemez.

Notlar ve Sınırlamalar

• Kodlar ve indirim tutarları değiştirilemez. Görünen name değerini güncelleyebilir ve active durumunu değiştirebilirsiniz; ancak percent_off, amount_off veya code alanları değiştirilemez. Farklı koşullara ihtiyaç duyuyorsanız yeni bir kupon oluşturun.
• times_redeemed otomatik olarak artar ve salt okunurdur — kampanya performansını takip etmek için kullanışlıdır.
• Kuponlar müşteri bazında uygulanır, sipariş bazında değil — bir kupon forever olarak ayarlanmışsa ve müşteri abone olursa, her yenileme indirimden yararlanır.