Cupoane

Creează coduri de reducere pe care clienții le pot aplica la checkout. Procentuale sau cu sumă fixă, limitate în timp sau cu un număr maxim de utilizări, o singură dată sau recurente.

Cupoanele sunt gestionate în Commerce panel > Products > Coupons din builder, sau prin SDK la proyecta.commerce.coupons.

Structura unui cupon

Câmp	Detalii
code	Codul promoțional pe care clienții îl introduc la checkout (ex. LAUNCH20)
percent_off sau amount_off	Reciproc exclusive. Procentul este între 1–100. Suma este exprimată în cea mai mică unitate monetară (cenți).
currency	Obligatoriu pentru reducerile de tip amount_off (cod ISO din trei litere). Acceptat la creare și transmis către Stripe, dar nu este stocat sau returnat ulterior de API.
duration	once (doar prima plată), repeating (pentru duration_in_months), sau forever
duration_in_months	Obligatoriu când duration este repeating
max_redemptions	Limita totală de utilizări pentru toți clienții
redeem_by	Data de expirare după care cuponul nu mai funcționează
name	Numele afișat clienților
active	Comutator pentru activare/dezactivare fără ștergere

Crearea unui cupon

Din sub-tab-ul Coupons, apasă Add coupon și completează câmpurile. Sau prin SDK:

// 20% reducere pentru totdeauna
await proyecta.commerce.coupons.create({
    code: 'LAUNCH20',
    name: 'Launch discount',
    percent_off: 20,
    duration: 'forever',
});

// $10 reducere, utilizare unică, expiră în 30 de zile
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% reducere pentru primele 3 luni ale unui abonament
await proyecta.commerce.coupons.create({
    code: 'EARLY3',
    percent_off: 50,
    duration: 'repeating',
    duration_in_months: 3,
});

Aplicarea unui cupon la checkout

Clienții pot introduce codul de cupon ei înșiși pe pagina de checkout găzduită de Stripe — câmpul pentru codul promoțional este afișat automat.

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

Transmiterea unui cod de cupon în mod programatic în apelul de checkout nu este încă suportată.

Listare, actualizare, dezactivare

// Listează toate cupoanele (afișează doar cupoanele create prin SDK)
const { data } = await proyecta.commerce.coupons.list();
for (const coupon of data.data) {
    console.log(coupon.code, coupon.times_redeemed, '/', coupon.max_redemptions);
}
// Folosește data.has_more și parametrul de interogare starting_after pentru paginare, dacă este necesar.

// Dezactivează un cupon (fără ștergere)
await proyecta.commerce.coupons.update({ couponId: 'coupon_123', active: false });

Notă: coupons.list() returnează doar cupoanele create prin SDK. Cupoanele create în Dashboard-ul builder-ului nu sunt vizibile prin coupons.list().

Note și limite

• Codurile și sumele de reducere sunt imuabile. Poți actualiza name-ul afișat și comuta active, dar nu și percent_off, amount_off sau code-ul în sine. Creează un cupon nou dacă ai nevoie de condiții diferite.
• times_redeemed se incrementează automat și este doar pentru citire — util pentru urmărirea performanței campaniilor.
• Cupoanele se aplică per client, nu per comandă — dacă un cupon este forever și un client se abonează, fiecare reînnoire beneficiază de reducere.