Coupon

Crea codici sconto che i clienti possono applicare al checkout. Percentuale o importo fisso, con scadenza temporale o limite di utilizzi, monouso o ricorrenti.

I coupon vengono gestiti nel pannello Commerce > Products > Coupons del builder, oppure tramite l’SDK con proyecta.commerce.coupons.

Struttura di un coupon

Campo	Note
code	Il codice promozionale che i clienti inseriscono al checkout (es. LAUNCH20)
percent_off o amount_off	Si escludono a vicenda. La percentuale è compresa tra 1 e 100. L’importo è espresso nella più piccola unità valutaria (centesimi).
currency	Obbligatorio per gli sconti amount_off (codice ISO a tre lettere). Accettato in fase di creazione e trasmesso a Stripe, ma non memorizzato né restituito dall’API in seguito.
duration	once (solo il primo pagamento), repeating (per duration_in_months), oppure forever
duration_in_months	Obbligatorio quando duration è repeating
max_redemptions	Limite totale di utilizzi tra tutti i clienti
redeem_by	Data di scadenza oltre la quale il coupon smette di funzionare
name	Nome visualizzato mostrato ai clienti
active	Interruttore per abilitare/disabilitare senza eliminare

Creare un coupon

Dalla scheda Coupons, clicca su Add coupon e compila i campi. In alternativa, tramite l’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,
});

Applicare un coupon al checkout

I clienti possono inserire il codice coupon direttamente nella pagina di checkout ospitata da Stripe — il campo per il codice promozionale viene mostrato automaticamente.

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

Il passaggio di un codice coupon in modo programmatico nella chiamata di checkout non è ancora supportato.

Elencare, aggiornare, disattivare

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

Nota: coupons.list() restituisce solo i coupon creati tramite l’SDK. I coupon creati nella Dashboard del builder non sono visibili tramite coupons.list().

Note e limitazioni

• I codici e gli importi degli sconti sono immutabili. Puoi aggiornare il name visualizzato e cambiare lo stato di active, ma non percent_off, amount_off o il code stesso. Crea un nuovo coupon se hai bisogno di condizioni diverse.
• times_redeemed si incrementa automaticamente ed è in sola lettura — utile per monitorare le performance delle campagne.
• I coupon si applicano per cliente, non per ordine — se un coupon è forever e un cliente si abbona, ogni rinnovo beneficia dello sconto.