VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Promoções e cupons

Listar e simular promoções

Lista as promoções públicas ativas da loja e simula quais promoções e quanto desconto um conjunto de itens receberia.

Estas duas rotas públicas servem para mostrar as ofertas da loja, não para aplicá-las. Ambas dependem do módulo de promoções: com o módulo desligado, respondem 403 {"error":"module_disabled","module":"promotions"}. O desconto de verdade só existe no carrinho e no checkout.

Listar promoções públicas

GET/api/v1/storefront/promotionsPública

Lista as promoções públicas ativas

Devolve as promoções que estão ativas agora e podem ser mostradas a qualquer visitante. Por segurança, não aparecem promoções que exigem um código de cupom ou que valem só para clientes ou grupos específicos. Dessas, o visitante nunca fica sabendo. Cada promoção sai só com campos de apresentação: não há condições, código, lista de clientes nem contagem de uso. Se a loja desligou cupons, promoções com código também são omitidas.

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página antes do filtro de promoções segmentadas.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/promotions?page=1&per_page=20"

Resposta

200Promoções ativas
json
{
  "page": 1,
  "per_page": 20,
  "total": 76,
  "total_pages": 4,
  "promotions": [
    {
      "id": "79077750-c988-4a47-9e57-5e7fd521d1ec",
      "name": "10% no carrinho inteiro",
      "description": "",
      "type": "percentage",
      "discount": 1000,
      "valid_from": "2026-09-09T20:53:20.38412Z",
      "valid_until": null,
      "zone": "cart",
      "priority": 0,
      "stackable": false
    },
    {
      "id": "1610f8c4-5e31-43dd-a2f3-d1e38a1d868e",
      "name": "Frete Grátis – São Paulo",
      "description": "",
      "type": "free_shipping",
      "discount": 0,
      "valid_from": "2026-09-09T17:13:29.224227Z",
      "valid_until": null,
      "zone": "cart",
      "priority": 0,
      "stackable": true
    }
  ]
}

Campos da resposta

promotionsarray
Promoções desta página que são públicas.
promotions[].iduuid
Id da promoção.
promotions[].namestring
Nome para exibir.
promotions[].descriptionstring
Texto livre da loja. Pode ser vazio.
promotions[].typestring
percentagefixedfree_shippingbuy_x_get_y
Tipo do desconto.
promotions[].discountinteger
Basis points quando percentage (1000 = 10%), centavos quando fixed. 0 nos demais tipos.
promotions[].max_discountinteger
Teto do desconto em centavos. Só aparece quando a promoção tem teto.
promotions[].valid_fromstring
Início da validade, RFC 3339. null se sem início.
promotions[].valid_untilstring
Fim da validade, RFC 3339. null se sem fim.
promotions[].zonestring
catalogcart
Onde a promoção atua.
promotions[].priorityinteger
Ordem de avaliação. Menor número, maior prioridade.
promotions[].stackableboolean
true quando pode somar com outras promoções.
totalinteger
Total de promoções ativas antes do filtro de públicas. Pode ser maior que o número que você consegue listar.
pageinteger
Página devolvida.
per_pageinteger
Tamanho de página usado.
total_pagesinteger
Total de páginas, calculado com total.

Erros

StatusQuandoCorpo
403Módulo de promoções desligado{"error":"module_disabled","module":"promotions"}
500Falha ao consultar{"error":"failed to list active promotions","detail":"..."}
Páginas podem vir incompletas

O filtro das promoções segmentadas é aplicado depois de paginar. Em uma loja com 76 promoções ativas, a página 2 com per_page=1 voltou vazia no teste, embora total_pages fosse 76. Nunca pare de paginar na primeira página curta: continue até page passar de total_pages, ou use um per_page grande.

Simular promoções

POST/api/v1/storefront/promotions/evaluateAutenticada

Simula quais promoções um conjunto de itens do carrinho receberia

Roda o motor de promoções com os dados que você manda e devolve as promoções que se aplicariam, o desconto total e se há frete grátis. A simulação não cria pedido, não baixa o uso de nenhuma promoção e não lê nem altera o carrinho do cliente. Se a requisição vier com login, os grupos de cliente dele entram na avaliação (promoções exclusivas de um grupo passam a valer); sem login, só valem as promoções abertas a todos.

Se a loja usa "cupom único" (use_single_coupon), só o primeiro cupom válido de coupon_codes conta.

Corpo da requisição

zonestringpadrão: cart
cartcatalog
Zona de promoções a avaliar.
cart_subtotalinteger
Soma dos itens em centavos, antes de descontos.
cart_totalinteger
Total do carrinho em centavos, para condições baseadas em total.
total_weightinteger
Peso total do carrinho (a mesma unidade dos pesos dos itens).
itemsarray

Itens do carrinho.

product_iduuidobrigatório
Produto.
category_idsarray
Ids (UUID) das categorias do produto, para condições por categoria.
vendor_iduuid
Seller (lojista) dono do produto.
brand_iduuid
Marca, para orçamentos de promoção por marca.
unit_priceinteger
Preço unitário em centavos.
priceinteger
Alias de unit_price (também em centavos). Envie um dos dois.
quantityinteger
Quantidade.
weightinteger
Peso da unidade.
featuresobject
Características do produto (chave: valor) para condições por característica.
coupon_codesarray
Códigos de cupom a considerar (strings).
shipping_countrystring
País de destino (BR).
shipping_statestring
UF de destino (SP).
shipping_zipstring
CEP de destino.
payment_method_idstring
Forma de pagamento, para promoções condicionadas ao meio de pagamento.
shipping_method_iduuid
Frete escolhido, para promoções de frete grátis por método.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/storefront/promotions/evaluate" \
  -H "Content-Type: application/json" \
  -d '{
  "zone": "cart",
  "cart_subtotal": 30000,
  "cart_total": 30000,
  "shipping_state": "SP",
  "items": [
    {
      "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "category_ids": ["8fcaf422-1631-4282-b503-85cc57380649"],
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "unit_price": 30000,
      "quantity": 1
    }
  ]
}'

Resposta

200Resultado da simulação
json
{
  "applied_promotions": [
    {
      "id": "c19df8c2-279f-46c3-81e4-d1e52aec733c",
      "name": "Progressiva 5% acima de R$ 100",
      "discount_type": "percentage",
      "discount": 1500,
      "free_shipping": false
    },
    {
      "id": "1610f8c4-5e31-43dd-a2f3-d1e38a1d868e",
      "name": "Frete Grátis – São Paulo",
      "discount_type": "multi",
      "discount": 0,
      "free_shipping": true,
      "bonus_type": "multi"
    }
  ],
  "total_discount": 1500,
  "free_shipping": true,
  "item_discounts": {}
}

Campos da resposta

applied_promotionsarray
Promoções que se aplicariam, na ordem de avaliação.
applied_promotions[].iduuid
Id da promoção.
applied_promotions[].namestring
Nome da promoção.
applied_promotions[].codestring
Código de cupom, quando a promoção foi ativada por um.
applied_promotions[].discount_typestring
Tipo do desconto (percentage, fixed, free_shipping, multi...).
applied_promotions[].discountinteger
Valor abatido por esta promoção, em centavos.
applied_promotions[].free_shippingboolean
true se esta promoção zera o frete.
applied_promotions[].bonus_typestring
Tipo de bônus quando a promoção entrega algo além de desconto.
total_discountinteger
Soma dos descontos em centavos.
free_shippingboolean
true se alguma promoção concede frete grátis.
free_shipping_method_iduuid
Quando presente, o frete grátis vale só para esse método.
item_discountsobject
Desconto por item: product_id para centavos. Vazio quando o desconto não é por item.
free_productsarray
Brindes: lista de {product_id, quantity}. Ausente quando não há.
budget_skippedarray
Promoções que casariam, mas foram puladas porque o orçamento da campanha acabou.

A resposta pode trazer também chaves de bônus que só são executados depois do pedido pago (give_coupons, give_cashback, give_usergroup_ids, assign_rep_ids). Elas descrevem o que o cliente ganharia depois da compra; nada é entregue pela simulação.

Erros

StatusQuandoCorpo
400Corpo que não é JSON{"error":"invalid request body","detail":"invalid character 'x' looking for beginning of value"}
403Módulo de promoções desligado{"error":"module_disabled","module":"promotions"}
500Falha ao avaliar{"error":"failed to evaluate promotions","detail":"..."}
Use para mensagens de incentivo, não para o total

A simulação é ótima para "Compre mais R$ 50 e ganhe frete grátis": mande o carrinho com um valor maior e veja se free_shipping vira true. Para o valor que o cliente vai pagar, use sempre Calcular o carrinho, que lê o carrinho real.

Veja também

  • Cupons automáticos do cliente
  • Calcular o carrinho
  • Cupom e vale-presente no checkout
Anterior
Promoções, cupons automáticos e alertas
Próxima
Cupons automáticos do cliente
Nesta página
  • Listar promoções públicas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Simular promoções
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também