Kupon

Buat kode diskon yang dapat digunakan pelanggan saat checkout. Persentase atau jumlah tetap, berbatas waktu atau dibatasi jumlah, sekali pakai atau berulang.

Kupon dikelola di Commerce panel > Products > Coupons sub-tab pada builder, atau melalui SDK di proyecta.commerce.coupons.

Anatomi sebuah kupon

Field	Keterangan
code	Kode promo yang diketik pelanggan saat checkout (mis. LAUNCH20)
percent_off atau amount_off	Saling eksklusif. Persentase bernilai 1–100. Jumlah dalam satuan mata uang terkecil (sen).
currency	Wajib untuk diskon amount_off (kode ISO tiga huruf). Diterima saat pembuatan dan diteruskan ke Stripe, tetapi tidak disimpan atau dikembalikan oleh API setelahnya.
duration	once (pembayaran pertama saja), repeating (untuk duration_in_months), atau forever
duration_in_months	Wajib diisi ketika duration bernilai repeating
max_redemptions	Total batas penggunaan di seluruh pelanggan
redeem_by	Tanggal kedaluwarsa setelah kupon tidak lagi berlaku
name	Nama tampilan yang ditunjukkan kepada pelanggan
active	Toggle untuk mengaktifkan/menonaktifkan tanpa menghapus

Membuat kupon

Dari sub-tab Coupons, klik Add coupon dan isi field yang tersedia. Atau melalui 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,
});

Menerapkan kupon saat checkout

Pelanggan dapat memasukkan kode kupon sendiri di halaman checkout yang di-host oleh Stripe — field kode promo ditampilkan secara otomatis.

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

Memasukkan kode kupon secara programatik dalam panggilan checkout belum didukung saat ini.

List, update, nonaktifkan

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

Catatan: coupons.list() hanya mengembalikan kupon yang dibuat melalui SDK. Kupon yang dibuat di Dashboard builder tidak terlihat melalui coupons.list().

Catatan dan batasan

• Kode dan jumlah diskon bersifat tidak dapat diubah. Kamu dapat memperbarui name tampilan dan toggle active, tetapi tidak percent_off, amount_off, atau code itu sendiri. Buat kupon baru jika kamu membutuhkan ketentuan yang berbeda.
• times_redeemed bertambah otomatis dan bersifat hanya-baca — berguna untuk melacak performa kampanye.
• Kupon berlaku per pelanggan, bukan per pesanan — jika kupon bersifat forever dan pelanggan berlangganan, setiap pembaruan langganan akan mendapatkan diskon tersebut.