Coupons

Erstelle Rabattcodes, die Kunden beim Checkout einlösen können. Prozentual oder als fester Betrag, zeitlich begrenzt oder mit Einlösungslimit, einmalig oder wiederkehrend.

Coupons werden im Commerce panel > Products > Coupons-Unterreiter des Builders oder über das SDK unter proyecta.commerce.coupons verwaltet.

Aufbau eines Coupons

Feld	Hinweise
code	Der Aktionscode, den Kunden beim Checkout eingeben (z. B. LAUNCH20)
percent_off oder amount_off	Gegenseitig ausschließend. Prozent ist 1–100. Betrag wird in der kleinsten Währungseinheit (Cent) angegeben.
currency	Erforderlich für amount_off-Rabatte (dreistelliger ISO-Code). Wird bei der Erstellung akzeptiert und an Stripe weitergeleitet, aber danach nicht gespeichert oder von der API zurückgegeben.
duration	once (nur erste Zahlung), repeating (für duration_in_months) oder forever
duration_in_months	Erforderlich, wenn duration auf repeating gesetzt ist
max_redemptions	Gesamtlimit über alle Kunden hinweg
redeem_by	Ablaufdatum, nach dem der Coupon nicht mehr funktioniert
name	Anzeigename, der Kunden angezeigt wird
active	Umschalten zum Aktivieren/Deaktivieren ohne Löschen

Einen Coupon erstellen

Klicke im Coupons-Unterreiter auf Add coupon und fülle die Felder aus. Oder über das 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,
});

Einen Coupon beim Checkout anwenden

Kunden können den Coupon-Code selbst auf der von Stripe gehosteten Checkout-Seite eingeben – das Feld für den Aktionscode wird automatisch angezeigt.

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

Das programmgesteuerte Übergeben eines Coupon-Codes im Checkout-Aufruf wird noch nicht unterstützt.

Auflisten, aktualisieren, deaktivieren

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

Hinweis: coupons.list() gibt nur Coupons zurück, die über das SDK erstellt wurden. Coupons, die im Builder-Dashboard erstellt wurden, sind über coupons.list() nicht sichtbar.

Hinweise und Einschränkungen

• Codes und Rabattbeträge sind unveränderlich. Du kannst den Anzeigenamen name aktualisieren und active umschalten, aber nicht percent_off, amount_off oder code selbst. Erstelle einen neuen Coupon, wenn du andere Konditionen benötigst.
• times_redeemed wird automatisch hochgezählt und ist schreibgeschützt – nützlich zur Erfolgsmessung von Kampagnen.
• Coupons gelten pro Kunde, nicht pro Bestellung – wenn ein Coupon auf forever gesetzt ist und ein Kunde ein Abonnement abschließt, erhält jede Verlängerung den Rabatt.