Cupons

Coupon é um código de desconto que você aplica em transações de um produto específico. Suporta dois tipos (percentual ou valor fixo), limite de uso global, expiração e ativação/desativação manual.

Modelo

{
  id: 'cpn_abc',
  productId: 'prd_xyz',          // escopo: este cupom só vale neste produto
  name: 'Black Friday 2026',     // label interno (não aparece pro cliente)
  code: 'BF2026',                // código que o cliente digita
  discountType: 'PERCENTAGE',    // PERCENTAGE | FIXED
  discountValue: 30,             // 30% se PERCENTAGE, R$ 30,00 se FIXED em BRL
  isActive: true,
  usageLimit: 100,               // null = ilimitado
  usageCount: 47,                // incrementa em cada transação succeeded
  expiresAt: '2026-11-30T23:59:59Z',
}

Tipos de desconto

PERCENTAGE

discountValue é interpretado como percentual (0–100). Aplica sobre o base_amount do produto.

produto R$ 497,00 + cupom 30% PERCENTAGE
→ cliente paga R$ 347,90
{ discountType: 'PERCENTAGE', discountValue: 30 }

FIXED

discountValue é interpretado como valor em centavos da base_currency do produto. Aplica como abatimento absoluto.

produto R$ 497,00 + cupom FIXED 5000 (R$ 50,00)
→ cliente paga R$ 447,00
{ discountType: 'FIXED', discountValue: 5000 }

Regras:

• Se discountValue >= base_amount, a cobrança é zerada (amount: 0) — não há "crédito" sobrando.
• Em multi-currency, a Zhex converte discountValue (FIXED) para a moeda da transação usando o FX lockado no PaymentIntent.

Validação no checkout

Quando um PaymentIntent é confirmado em fluxos que carregam cupom (checkout hosted, payment links com cupom anexado), a Zhex valida na hora:

1. code existe e bate com o productId?
2. isActive: true?
3. expiresAt está no futuro (ou null)?
4. usageCount < usageLimit (ou usageLimit null)?

Se qualquer um falhar, a confirmação retorna erro com code específico (coupon_expired, coupon_exhausted, coupon_inactive, coupon_not_found). Se passar, o desconto é aplicado, usageCount incrementa e a transação registra o uso em TransactionCoupon.

Cupons + Refund

Quando você refunda uma transação que usou cupom, a Zhex decrementa usageCount automaticamente — o slot volta para o pool e fica disponível para outro uso.

Cupons + Chargeback

Em chargeback, a transação é estornada compulsoriamente, e o usageCount também é decrementado — mesma lógica do refund. Veja Chargeback.

Cupons em assinatura

Cupom em uma CustomerSubscription aplica apenas na primeira cobrança por padrão. Para descontos recorrentes (ex: 20% off por 3 meses), hoje você cria planos separados no dashboard. Suporte nativo a desconto recorrente está no roadmap.

Boas práticas

• code MAIÚSCULO e curto. BF2026 > BlackFriday-2026!. Reduz typo no checkout.
• usageLimit para campanhas com escassez (limite de 50 vagas) — gera urgency real, não fake.
• expiresAt em UTC. Se sua campanha "termina à meia-noite", use a TZ certa: 2026-11-30T23:59:59-03:00 para final do dia BRT.
• Não exponha cupons admin no front. Cupons sensíveis (admin/staff) devem ficar atrás de auth — nunca expostos publicamente em URLs ou JS bundles.

Próximos passos