Coupons

Créez des codes de réduction que les clients peuvent appliquer au moment du paiement. En pourcentage ou montant fixe, limités dans le temps ou plafonnés, à usage unique ou récurrents.

Les coupons sont gérés dans le panneau Commerce > Produits > Coupons du builder, ou via le SDK à proyecta.commerce.coupons.

Anatomie d’un coupon

Champ	Remarques
code	Le code promo que les clients saisissent au moment du paiement (ex. LAUNCH20)
percent_off ou amount_off	Mutuellement exclusifs. Le pourcentage est compris entre 1 et 100. Le montant est exprimé dans la plus petite unité monétaire (centimes).
currency	Obligatoire pour les remises de type amount_off (code ISO à trois lettres). Accepté à la création et transmis à Stripe, mais non stocké ni renvoyé par l’API par la suite.
duration	once (premier paiement uniquement), repeating (pour duration_in_months), ou forever
duration_in_months	Obligatoire lorsque duration est repeating
max_redemptions	Plafond total toutes utilisations confondues
redeem_by	Date d’expiration après laquelle le coupon cesse de fonctionner
name	Nom d’affichage présenté aux clients
active	Bascule pour activer/désactiver sans supprimer

Créer un coupon

Depuis l’onglet Coupons, clique sur Add coupon et remplis les champs. Ou via le 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,
});

Appliquer un coupon au moment du paiement

Les clients peuvent saisir eux-mêmes le code promo sur la page de paiement hébergée par Stripe — le champ de code promo s’affiche automatiquement.

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

La transmission d’un code coupon par programmation dans l’appel de checkout n’est pas encore prise en charge.

Lister, mettre à jour, désactiver

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

Remarque : coupons.list() ne retourne que les coupons créés via le SDK. Les coupons créés depuis le Dashboard du builder ne sont pas visibles via coupons.list().

Remarques et limites

• Les codes et les montants de remise sont immuables. Tu peux mettre à jour le name d’affichage et basculer active, mais pas percent_off, amount_off ni code lui-même. Crée un nouveau coupon si tu as besoin de conditions différentes.
• times_redeemed s’incrémente automatiquement et est en lecture seule — pratique pour suivre les performances d’une campagne.
• Les coupons s’appliquent par client, et non par commande — si un coupon est forever et qu’un client souscrit un abonnement, chaque renouvellement bénéficie de la remise.