Cupons

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

Os cupons são gerenciados no painel do seu app em Admin > Commerce > Products, na seção Coupons, e também na aba Cupones do painel de administração do seu app publicado.

Anatomia de um cupom

Campo	Notas
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 com amount_off (código ISO de três letras). Aceito na criação e encaminhado ao Stripe, mas não armazenado nem retornado pela API depois.
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. Alguns formatos comuns:

Objetivo	Configurações
20% de desconto para sempre	percent_off: 20, duration forever
R$10 de desconto, uso único, expira em 30 dias	amount_off: 1000, currency USD, duration once, max redemptions 1, redeem-by 30 dias à frente
50% de desconto nos primeiros 3 meses de uma assinatura	percent_off: 50, duration repeating, duration in months 3

Ou simplesmente peça à IA: "Create a LAUNCH20 coupon for 20% off forever."

Aplicar um cupom no checkout

Há duas formas de um cliente usar um código:

• Na página de checkout do Stripe — o campo de código promocional é exibido automaticamente, então o cliente pode digitar o código lá sem nenhuma configuração adicional da sua parte.
• No seu próprio carrinho — adicione um campo de código promocional ao seu carrinho e passe o que o cliente digitou para a chamada de checkout como couponCode. O servidor valida o código e calcula o desconto a partir dos seus dados de commerce (nunca a partir de um valor fornecido pelo navegador), registra isso no pedido e vincula o cupom Stripe correspondente para que a cobrança seja correta.

Peça à IA: "Add a promo code field to the cart and apply it at checkout."

Listar, atualizar, desativar

A sub-aba Coupons lista todos os cupons com a quantidade de resgates realizados em relação ao limite, para que você acompanhe o desempenho das campanhas de forma rápida. A edição é intencionalmente limitada — veja abaixo — mas você pode desativar qualquer cupom sem excluí-lo, o que o impede de funcionar no checkout imediatamente.

Notas 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 pode alterar 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 das campanhas.
• Os cupons são aplicados por cliente, não por pedido — se um cupom for forever e um cliente fizer uma assinatura, cada renovação receberá o desconto.