Coupons

Maak kortingscodes aan die klanten kunnen gebruiken bij het afrekenen. Percentueel of vast bedrag, tijdgebonden of gemaximeerd, eenmalig of terugkerend.

Coupons worden beheerd via het Commerce panel > Products > Coupons-subtabblad in de builder, of via de SDK op proyecta.commerce.coupons.

Anatomie van een coupon

Veld	Opmerkingen
code	De promotiecode die klanten invoeren bij het afrekenen (bijv. LAUNCH20)
percent_off of amount_off	Onderling exclusief. Percentage is 1–100. Bedrag is in de kleinste valuta-eenheid (centen).
currency	Vereist voor amount_off-kortingen (drieletterige ISO-code). Wordt geaccepteerd bij aanmaken en doorgegeven aan Stripe, maar daarna niet opgeslagen of geretourneerd door de API.
duration	once (alleen eerste betaling), repeating (voor duration_in_months), of forever
duration_in_months	Vereist wanneer duration gelijk is aan repeating
max_redemptions	Totaal maximum over alle klanten
redeem_by	Vervaldatum waarna de coupon niet meer geldig is
name	Weergavenaam die aan klanten wordt getoond
active	Schakelaar om in/uit te schakelen zonder te verwijderen

Een coupon aanmaken

Klik in het subtabblad Coupons op Add coupon en vul de velden in. Of via de 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,
});

Een coupon toepassen bij het afrekenen

Klanten kunnen de couponcode zelf invoeren op de door Stripe gehoste afrekenpagina — het veld voor de promotiecode wordt automatisch weergegeven.

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

Het programmatisch meegeven van een couponcode in de checkout-aanroep wordt nog niet ondersteund.

Weergeven, bijwerken, deactiveren

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

Opmerking: coupons.list() retourneert alleen coupons die via de SDK zijn aangemaakt. Coupons die in het builder-dashboard zijn aangemaakt, zijn niet zichtbaar via coupons.list().

Opmerkingen en beperkingen

• Codes en kortingsbedragen zijn onveranderlijk. Je kunt de weergavenaam name bijwerken en active in- of uitschakelen, maar niet percent_off, amount_off of code zelf. Maak een nieuwe coupon aan als je andere voorwaarden nodig hebt.
• times_redeemed wordt automatisch verhoogd en is alleen-lezen — handig voor het bijhouden van campagneprestaties.
• Coupons gelden per klant, niet per bestelling — als een coupon forever is en een klant een abonnement neemt, krijgt elke verlenging de korting.