कूपन

ऐसे डिस्काउंट कोड बनाएं जिन्हें ग्राहक checkout पर लगा सकते हैं। Percentage या fixed-amount, समय-सीमित या capped, एक बार या बार-बार उपयोग के लिए।

कूपन builder के Commerce panel > Products > Coupons sub-tab में, या SDK के ज़रिए proyecta.commerce.coupons पर manage किए जाते हैं।

कूपन की संरचना

फ़ील्ड	विवरण
code	वह promo code जो ग्राहक checkout पर टाइप करते हैं (जैसे LAUNCH20)
percent_off या amount_off	दोनों एक साथ उपयोग नहीं हो सकते। Percent 1–100 के बीच होता है। Amount सबसे छोटी currency unit (cents) में होती है।
currency	amount_off discounts के लिए ज़रूरी है (तीन अक्षरों का ISO code)। Creation के समय स्वीकार किया जाता है और Stripe को भेजा जाता है, लेकिन बाद में API द्वारा store या return नहीं किया जाता।
duration	once (केवल पहला payment), repeating (duration_in_months के लिए), या forever
duration_in_months	जब duration repeating हो तो ज़रूरी है
max_redemptions	सभी ग्राहकों में कुल उपयोग की सीमा
redeem_by	वह expiration date जिसके बाद कूपन काम करना बंद कर देता है
name	ग्राहकों को दिखाया जाने वाला display name
active	बिना delete किए enable/disable करने का toggle

कूपन बनाएं

Coupons sub-tab से 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-hosted checkout page पर खुद कूपन कोड दर्ज कर सकते हैं — promo code फ़ील्ड अपने आप दिखाई देती है।

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

Checkout call में programmatically कूपन कोड पास करना अभी supported नहीं है।

List, update, deactivate करें

// 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() केवल वे कूपन return करता है जो SDK के ज़रिए बनाए गए हों। Builder Dashboard में बनाए गए कूपन coupons.list() के ज़रिए दिखाई नहीं देते।

नोट्स और सीमाएं

• Codes और discount amounts अपरिवर्तनीय हैं। आप display name अपडेट कर सकते हैं और active toggle कर सकते हैं, लेकिन percent_off, amount_off, या code नहीं बदल सकते। अलग शर्तों के लिए एक नया कूपन बनाएं।
• times_redeemed अपने आप बढ़ता है और read-only है — campaign performance track करने के लिए उपयोगी है।
• कूपन प्रति ग्राहक लागू होते हैं, प्रति order नहीं — अगर कोई कूपन forever है और ग्राहक subscribe करता है, तो हर renewal पर discount मिलेगा।