Cupons automáticos

Um cupom automático é um cupom que a plataforma gera e entrega sozinha depois que um cliente faz uma compra: "concluiu o primeiro pedido, ganha 10% na próxima". O lojista não cria cada código; ele cadastra uma regra (gatilho, desconto, validade) e, a cada pedido concluído que casar com a regra, nasce um código único para aquele cliente, enviado por e-mail. É diferente de gerar códigos descartáveis a partir de uma promoção, que é uma ação manual do lojista.

Como funciona

Gatilhos (trigger_type)

Regras de seller (com vendor_id) avaliam apenas a parte do pedido que é daquele seller (subtotal e contagem de pedidos dele), e o cupom gerado só desconta itens dele.

Ciclo de vida do cupom gerado

1. Gerado com max_uses usos e validade de valid_days dias. Se send_email é true, o cliente recebe o código por e-mail.
2. Usado no carrinho como qualquer cupom. O valor mínimo da regra (min_order_amount) vira condição de subtotal.
3. Esgotado ao atingir max_uses, ou expirado passada a validade.
4. Desativado se o pedido que o gerou for cancelado.

Conceitos importantes

O cupom não é preso ao cliente

O cupom é gravado com o cliente que o ganhou (user_id) e o checkout limita a 1 uso por cliente, mas quem tiver o código pode digitá-lo. Se isso importa para a campanha, use max_uses baixo e valid_days curto.

Status da regra

A regra nasce A (ativa). Só regras A são avaliadas. Na entrada você pode enviar active ou disabled (ou as letras A e D).

Endpoints

Erros comuns

• Achar que a regra vale para pedidos antigos. O gatilho só roda quando um pedido muda para concluído depois que a regra existe.
• Misturar unidades. discount_value é em pontos-base para percentage e em centavos para fixed; trigger_value de min_order_amount é em centavos.
• Usar UUID no caminho. O {id} aqui é um número inteiro; texto leva 400 invalid rule ID.
• Excluir a regra esperando invalidar os códigos já enviados. A exclusão apaga os registros da regra e dos cupons gerados, mas as promoções-espelho que o checkout aceita continuam ativas até expirar ou serem desativadas em Promoções.
• Status inválido. Uma palavra de status desconhecida com mais de uma letra vira A (ativa), nunca é recusada. Envie active ou disabled.
• Esperar 404 ao alterar regra inexistente. O PUT responde 400 com auto-coupon rule not found.

Próximos passos