Cupons

Crie códigos de desconto que os clientes podem aplicar no checkout. Percentual ou valor fixo, com prazo limitado ou limite de uso, de uso único ou recorrente.

Os cupons são gerenciados no painel Commerce > Products > Coupons do builder, ou através do SDK em proyecta.commerce.coupons.

Anatomia de um cupom

Campo	Observações
code	O código promocional que os clientes digitam no checkout (ex.: LAUNCH20)
percent_off ou amount_off	Mutuamente exclusivos. O percentual vai de 1 a 100. O valor é na menor unidade monetária (centavos).
currency	Obrigatório para descontos em amount_off (código ISO de três letras). Aceito na criação e repassado ao Stripe, mas não armazenado nem retornado pela API posteriormente.
duration	once (apenas no primeiro pagamento), repeating (por duration_in_months), ou forever
duration_in_months	Obrigatório quando duration é repeating
max_redemptions	Limite total de resgates entre todos os clientes
redeem_by	Data de expiração após a qual o cupom deixa de funcionar
name	Nome de exibição mostrado aos clientes
active	Alternância para ativar/desativar sem excluir

Criar um cupom

Na sub-aba Coupons, clique em Add coupon e preencha os campos. Ou via 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,
});

Aplicar um cupom no checkout

Os clientes podem inserir o código do cupom por conta própria na página de checkout hospedada pelo Stripe — o campo de código promocional é exibido automaticamente.

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

Passar um código de cupom de forma programática na chamada de checkout ainda não é suportado.

Listar, atualizar, desativar

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

Observação: coupons.list() retorna apenas os cupons criados via SDK. Cupons criados no Dashboard do builder não são visíveis através de coupons.list().

Observações e limitações

• Códigos e valores de desconto são imutáveis. Você pode atualizar o name de exibição e alternar o active, mas não percent_off, amount_off ou o próprio code. Crie um novo cupom se precisar de condições diferentes.
• times_redeemed é incrementado automaticamente e é somente leitura — útil para acompanhar o desempenho de campanhas.
• Os cupons se aplicam por cliente, não por pedido — se um cupom for forever e um cliente assinar, cada renovação receberá o desconto.