Kupony

Twórz kody rabatowe, które klienci mogą zastosować przy kasie. Procentowe lub kwotowe, z limitem czasowym lub ilościowym, jednorazowe lub cykliczne.

Kupony są zarządzane w panelu buildera: Commerce panel > Products > Coupons, lub za pomocą SDK pod adresem proyecta.commerce.coupons.

Budowa kuponu

Pole	Uwagi
code	Kod promocyjny wpisywany przez klientów przy kasie (np. LAUNCH20)
percent_off lub amount_off	Wzajemnie wykluczające się. Procent wynosi 1–100. Kwota podawana jest w najmniejszej jednostce waluty (groszach/centach).
currency	Wymagane dla rabatów amount_off (trzyliterowy kod ISO). Przyjmowane przy tworzeniu i przekazywane do Stripe, ale nie przechowywane ani nie zwracane przez API.
duration	once (tylko pierwsza płatność), repeating (przez duration_in_months), lub forever
duration_in_months	Wymagane, gdy duration ma wartość repeating
max_redemptions	Łączny limit realizacji dla wszystkich klientów
redeem_by	Data wygaśnięcia, po której kupon przestaje działać
name	Nazwa wyświetlana klientom
active	Przełącznik umożliwiający włączenie/wyłączenie bez usuwania

Tworzenie kuponu

Na karcie Coupons, kliknij Add coupon i wypełnij pola. Możesz też skorzystać z 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,
});

Stosowanie kuponu przy kasie

Klienci mogą samodzielnie wpisać kod kuponu na stronie kasy hostowanej przez Stripe — pole na kod promocyjny jest wyświetlane automatycznie.

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

Programowe przekazywanie kodu kuponu w wywołaniu kasy nie jest jeszcze obsługiwane.

Listowanie, aktualizowanie, dezaktywowanie

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

Uwaga: coupons.list() zwraca wyłącznie kupony utworzone za pomocą SDK. Kupony utworzone w panelu buildera nie są widoczne przez coupons.list().

Uwagi i ograniczenia

• Kody i wartości rabatów są niezmienne. Możesz zaktualizować wyświetlaną nazwę name i przełączyć active, ale nie percent_off, amount_off ani code. Jeśli potrzebujesz innych warunków, utwórz nowy kupon.
• times_redeemed jest automatycznie inkrementowany i tylko do odczytu — przydatny do śledzenia wyników kampanii.
• Kupony są stosowane per klient, nie per zamówienie — jeśli kupon ma wartość forever i klient wykupi subskrypcję, każde odnowienie otrzyma rabat.