Купони

Створюй промокоди, які покупці можуть застосовувати при оформленні замовлення. Відсоткові або фіксовані, обмежені за часом або кількістю використань, одноразові або повторювані.

Купони керуються у вкладці Commerce panel > Products > Coupons в builder’і або через SDK за адресою proyecta.commerce.coupons.

Структура купона

Поле	Примітки
code	Промокод, який покупець вводить при оформленні замовлення (наприклад, LAUNCH20)
percent_off або amount_off	Взаємовиключні. Відсоток — від 1 до 100. Сума — у найменших одиницях валюти (центи).
currency	Обов’язково для знижок типу amount_off (тризначний ISO-код). Приймається при створенні та передається до Stripe, але не зберігається і не повертається API надалі.
duration	once (лише перший платіж), repeating (для duration_in_months) або forever
duration_in_months	Обов’язково, коли duration має значення repeating
max_redemptions	Загальний ліміт використань для всіх покупців
redeem_by	Дата закінчення дії, після якої купон перестає працювати
name	Назва, яка відображається покупцям
active	Перемикач для увімкнення/вимкнення без видалення

Створення купона

У вкладці Coupons натисни Add coupon і заповни поля. Або через 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,
});

Застосування купона при оформленні замовлення

Покупці можуть самостійно ввести промокод на сторінці оформлення замовлення, яку хостить Stripe, — поле для промокоду відображається автоматично.

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

Передача промокоду програмно у виклику checkout наразі не підтримується.

Перегляд, оновлення, деактивація

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

Примітка: coupons.list() повертає лише купони, створені через SDK. Купони, створені в Dashboard builder’а, не відображаються через coupons.list().

Примітки та обмеження

• Коди та суми знижок незмінні. Ти можеш оновити відображувану name та перемикати active, але не percent_off, amount_off або сам code. Якщо потрібні інші умови — створи новий купон.
• times_redeemed автоматично збільшується і доступний лише для читання — зручно для відстеження ефективності кампаній.
• Купони застосовуються для кожного покупця окремо, а не для кожного замовлення — якщо купон має тип forever і покупець оформлює підписку, знижка застосовуватиметься при кожному поновленні.