Promoções e cupons

Uma promoção é uma regra de desconto que a loja cadastra uma vez e a plataforma aplica sozinha no carrinho ou no preço da vitrine. Quando a promoção tem um código ela funciona como cupom: o cliente precisa digitar o código. Sem código ela é automática. Estas são as rotas do administrador da loja (/api/v1/admin/...); a vitrine e o checkout leem as mesmas promoções para calcular o que o cliente paga.

Como funciona

Ciclo de vida

Uma promoção ativa só desconta quando a vigência está aberta (valid_from já passou e valid_until ainda não), o limite de usos (usage_limit, per_user_limit) não foi atingido, as condições batem com o carrinho e nenhum orçamento associado (veja Orçamentos e grupos) está esgotado.

Fluxo típico de integração

1. Escolha a zona e o tipo
   Decida se o desconto aparece no preço do produto (catalog) ou só quando o cliente monta o carrinho (cart), e qual type usar.
2. Crie a promoção
   POST /api/v1/admin/promotions com nome, tipo, desconto e, se for cupom, o code. Veja Criar promoção.
3. Confira o cupom
   POST /api/v1/admin/coupons/validate diz se o código seria aceito e qual desconto daria. Veja Cupons.
4. Acompanhe o resultado
   GET /api/v1/admin/promotions/stats mostra usos, clientes únicos e desconto concedido. Veja Estatísticas e projeção.
5. Encerre
   Desative com PUT (status inactive) ou exclua. Para muitas de uma vez use Ações em lote.

Conceitos importantes

Tipos de promoção (type)

Os tipos do editor do painel são quatro. Os demais existem para o modelo de bônus e para promoções criadas por integração.

Um valor fora da lista leva 400 e a mensagem traz todos os tipos aceitos. Um desconto negativo, ou um percentage acima de 10000, também é recusado.

Zona: catálogo ou carrinho

• catalog: o desconto entra no preço do produto na vitrine, na busca e na mini-loja. Só enxerga condições do produto (produto, categoria, seller, preço, quantidade, usuário). Condições de carrinho (subtotal, frete, forma de pagamento, cupom) são recusadas com 400.
• cart: o desconto é calculado quando o cliente monta o carrinho e no checkout. Aceita todas as condições.

Se você não enviar zone, a plataforma escolhe cart para buy_x_get_y, para tipos que o catálogo não calcula e para qualquer promoção com código; as demais ficam em catalog. Uma zona escrita à mão que não calcula o tipo (por exemplo buy_x_get_y em catalog) é recusada com 400.

Condições

conditions é um objeto simples, todas as chaves opcionais:

Para regras com E/OU use condition_groups: um objeto {"set":"all"|"any","set_value":true,"conditions":[...]} cujas folhas são {"type":"subtotal","operator":"gte","value":20000} e que podem ter grupos dentro de grupos. Operadores: eq, neq, lt, gt, lte, gte, in, nin, cont, ncont. Tipos de folha válidos em qualquer zona: price, product_quantity, categories, products, vendor, users, feature. Só na zona cart: subtotal, products_number, total_weight, country, state, zip_postal_code, customer_state, customer_city, customer_cep_range, shipping_zone, customer_region, payment_method, shipping_method, coupon_code, multiple_coupon_codes, once_per_customer, number_of_usages, purchased_products, usergroup, product_qty, product_min_qty, category_qty, category_min_qty, first_order, first_order_only, once_per_cnpj, days_since_last_order, no_orders_in_days, categories_purchased_in_period, categories_prev_month, avg_ticket_p6m, loyalty_tier. Um tipo desconhecido é recusado, nunca ignorado.

Cupom: um código por promoção

O campo code guarda um código por promoção. A plataforma o grava em maiúsculas, sem caracteres invisíveis (por exemplo o espaço de largura zero que o WhatsApp cola junto) e a busca na hora de usar ignora maiúsculas e minúsculas. Dois códigos iguais não podem existir em promoções não excluídas: o segundo leva 409 coupon_code_in_use. Para ter muitos códigos descartáveis a partir de uma promoção-modelo use generate-auto-coupons (veja Cupons).

Quem é o dono: loja toda ou seller

vendor_id vazio significa promoção da loja/marketplace: entra no cálculo automático. Com vendor_id preenchido a promoção é de um seller, o desconto incide só sobre os itens dele e ela só funciona por código de cupom, nunca de forma automática.

Proteções que a API aplica por você

• Loja toda por engano. Uma promoção de catálogo sem nenhum produto nem categoria vale para a loja inteira. Para gravá-la você precisa confirmar com ?confirm_store_wide=true; sem isso a resposta é 400 store_wide_unconfirmed. A mesma pergunta aparece quando uma edição muda o alcance e o resultado é a loja toda.
• Piso de margem. Se a loja usa o Protetor de Margem, uma oferta que leva algum produto abaixo da margem mínima é recusada com 422 e o detalhamento da conta. Um token de exceção aprovado vai no cabeçalho X-Margin-Override.
• Campo desconhecido não passa calado. Chaves do corpo que a rota não conhece são devolvidas em ignored_fields e warning (e no cabeçalho X-Campos-Ignorados). Um PUT que não muda nada leva 400 em vez de 200.

Endpoints

Erros comuns

• Mandar discount: 10 achando que é 10%. O percentual é em pontos-base: 10% é 1000. 10 seria 0,1%.
• Datas sem hora. valid_from e valid_until são RFC 3339 completos (2026-12-31T23:59:59-03:00). 2026-12-31 leva 400 com o formato aceito na mensagem.
• Usar nomes de outro sistema. title, start_at, end_at, from_date e expiry_date não existem na entrada. A resposta devolve from_date/expiry_date, mas quem lê a resposta e devolve esses nomes não define a vigência: use valid_from e valid_until. Sem valid_until a promoção vale para sempre.
• Promoção de catálogo sem alvo. Sem produtos nem categorias ela desconta a loja inteira. A API pede confirm_store_wide=true justamente para isso.
• Condição de carrinho na zona catalog. subtotal, coupon_code e semelhantes só existem em cart.
• Tentar um segundo cupom na mesma promoção. POST /promotions/{id}/coupons responde 409 se já existe código; troque com PUT ou gere códigos descartáveis.
• Esperar que null limpe um campo. No PUT, null ou vazio significa "não mexe". A única exceção é "code": null, que remove o código.

Próximos passos