| url | No | Link do cupom. Use sem "code" para um cupom resgatável direto no link. | |
| code | No | Código do cupom (ex.: BLACK10). Opcional se informar "url". | |
| site | No | Loja ou marketplace do cupom (ex.: Shopee). Sem nome/ID, identifica pelo domínio mapeado do link. | |
| coupons | No | Lote de cupons (até 50), cada um com code OU url e os demais campos. convert_url no topo vale para todos os itens que não disserem o contrário. | |
| site_id | No | ID do site obtido em list_coupon_categories. Tem prioridade sobre o nome e a identificação automática. | |
| raw_text | No | Opcional. Texto original do cupom (trilha de auditoria da ingestão). | |
| starts_at | No | Início de vigência — data ISO ou epoch. Antes dessa data o cupom não aparece como ativo. NUNCA use DD/MM/AAAA. Opcional. | |
| expires_at | No | Validade. Prefira data ISO com hora e fuso, ex.: "2026-12-31T23:59:59-03:00" (fim do dia no horário de Brasília). Data solta ("2026-12-31") é interpretada como meia-noite UTC — o cupom expira às 21h do dia ANTERIOR no Brasil. Também aceita epoch Unix em segundos ou milissegundos. NUNCA use DD/MM/AAAA. Opcional. | |
| convert_url | No | Se true, converte a "url" em link de afiliado antes de cadastrar. Se a conversão falhar, o cupom NÃO é salvo (nunca se publica a URL crua). Padrão: false. | |
| description | No | Descrição/condições do cupom. | |
| is_cashback | No | Opcional. true = o cupom é cashback (não desconto direto no carrinho). | |
| is_sold_out | No | Opcional. true = marca o cupom como ESGOTADO (o bot exibe o selo "Esgotado" em vez do botão de resgate); false = volta a disponível. Como o cadastro é upsert (dedup por loja+code ou loja+url), repita o mesmo code/url do cupom já cadastrado para atualizar só esse estado. | |
| max_discount | No | Opcional. Teto do desconto (em reais). SÓ se aplica a discount_type="percent" — em "amount" (ou sem tipo) é ignorado/limpo automaticamente. | |
| min_purchase | No | Opcional. Valor mínimo da compra (em reais) para o cupom valer. | |
| discount_type | No | Opcional. Tipo de desconto: "percent" (em %) ou "amount" (em reais). Combine com discount_value. | |
| discount_value | No | Opcional. Valor do desconto — em % quando discount_type="percent", em reais quando "amount" (ex.: 15 = 15% ou R$15). | |