Купоны

Создавай промокоды, которые покупатели вводят при оформлении заказа. Процентные или фиксированные скидки, ограниченные по времени или количеству использований, разовые или регулярные.

Купонами можно управлять в 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% скидки навсегда
await proyecta.commerce.coupons.create({
    code: 'LAUNCH20',
    name: 'Launch discount',
    percent_off: 20,
    duration: 'forever',
});

// $10 скидки, одноразовый, истекает через 30 дней
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% скидки на первые 3 месяца подписки
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 пока не поддерживается.

Список, обновление, деактивация

// Получить все купоны (возвращает только купоны, созданные через SDK)
const { data } = await proyecta.commerce.coupons.list();
for (const coupon of data.data) {
    console.log(coupon.code, coupon.times_redeemed, '/', coupon.max_redemptions);
}
// При необходимости используй пагинацию через data.has_more и параметр запроса starting_after.

// Отключить купон (без удаления)
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 и покупатель оформил подписку, скидка будет действовать при каждом продлении.