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

Listar e detalhar promoções

Lista as promoções da loja com filtros e paginação e devolve o detalhe de uma promoção.

Use a lista para montar uma tela de gestão ou sincronizar as promoções com outro sistema. O detalhe de uma promoção acrescenta labels, o nome legível de cada produto, categoria ou seller citado nas condições, para você não precisar resolver os ids um a um. Promoções excluídas não aparecem; as inativas (D) e as expiradas (E) aparecem.

Listar promoções

GET/api/v1/admin/promotionsAdmin

Lista promoções, da mais nova para a mais antiga, com filtros

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100. Fora disso volta ao padrão.
statusstring
Filtra pelo status. Aceita active, inactive, disabled, expired, draft ou a letra.
searchstring
Busca parte do nome ou do código, sem diferenciar maiúsculas.
zonestring
cartcatalog
cart ou catalog.
vendor_iduuid
Só promoções deste seller.
marketplace_onlyboolean
true devolve só as promoções da loja (sem seller). Se vendor_id vier junto, ele vence.

Exemplo de requisição: listar

bash
curl "$BASE_URL/api/v1/admin/promotions?status=active&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Página de promoções
json
{
  "promotions": [
    {
      "id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
      "name": "Black Friday 10% nas camisas",
      "type": "percentage",
      "code": "BLACK10",
      "discount": 1000,
      "status": "A",
      "zone": "cart",
      "valid_from": "2026-11-27T03:00:00Z",
      "valid_until": "2026-11-30T02:59:59Z",
      "usage_limit": 500,
      "usage_count": 12
    }
  ],
  "total": 21276,
  "page": 1,
  "per_page": 20,
  "total_pages": 1064
}

Campos da resposta

promotionsarray
Promoções da página. Lista vazia vem como null.
totalinteger
Total de promoções que casam com o filtro.
pageinteger
Página devolvida.
per_pageinteger
Tamanho da página usado.
total_pagesinteger
Total de páginas.

Cada item da lista traz todos os campos descritos abaixo; o exemplo mostra só alguns.

Erros: listar

StatusQuandoCorpo de exemplo
401Token ausente ou inválido.{"error":"authentication required"}
403O módulo promotions está desligado na loja.{"error":"module_disabled","module":"promotions"}
403O usuário não tem o privilégio exigido (view_promotions para ler, manage_promotions para gravar).{"error":"insufficient privileges","required":"manage_promotions"}
500Falha ao consultar o banco.{"error":"failed to list promotions","detail":"..."}

Detalhar uma promoção

GET/api/v1/admin/promotions/{id}Admin

Detalha uma promoção, com os nomes das condições resolvidos

Parâmetros de caminho

iduuidobrigatório
Id da promoção, UUID completo.

Exemplo de requisição: detalhar

bash
curl "$BASE_URL/api/v1/admin/promotions/7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30" \
  -H "Authorization: Bearer $TOKEN"

Resposta: detalhar

200Promoção encontrada
json
{
  "id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "name": "Black Friday 10% nas camisas",
  "description": "",
  "type": "percentage",
  "code": "BLACK10",
  "discount": 1000,
  "conditions": { "min_cart_total": 20000 },
  "usage_limit": 500,
  "usage_count": 0,
  "valid_from": "2026-11-27T03:00:00Z",
  "valid_until": "2026-11-30T02:59:59Z",
  "status": "A",
  "priority": 0,
  "stop_other_rules": false,
  "stackable": false,
  "zone": "cart",
  "condition_groups": null,
  "bonus_type": null,
  "bonus_config": null,
  "bonuses": [],
  "free_shipping_method_id": null,
  "per_user_limit": 1,
  "created_at": "2026-10-11T14:02:10.482113Z",
  "updated_at": "2026-10-11T14:02:10.482113Z",
  "promotion_id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "coupon_id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "bonus_value": 1000,
  "from_date": 1795748400,
  "expiry_date": 1796007599,
  "users": 0,
  "timestamp": 1791727330,
  "updated_timestamp": 1791727330
}

Campos da resposta

iduuid
Identificador da promoção (UUID).
vendor_iduuid | omitted
Seller dono da promoção. Ausente quando a promoção vale para a loja toda.
namestring
Nome interno, mostrado no painel.
descriptionstring
Descrição livre. Pode ser vazia.
typestring
Tipo da promoção (veja a tabela de tipos na home da seção).
codestring | null
Código do cupom, sempre em maiúsculas. null quando a promoção é automática.
discountinteger
Valor do desconto. Em percentage são pontos-base (1000 = 10%). Em fixed são centavos (2500 = R$ 25,00).
max_discountinteger | omitted
Teto do desconto em centavos. Ausente quando não há teto.
conditionsobject
Condições simples (veja a home da seção). {} quando não há.
condition_groupsobject | null
Condições aninhadas E/OU. null quando não há.
usage_limitinteger
Máximo de usos no total. 0 = sem limite.
per_user_limitinteger | omitted
Máximo de usos por cliente.
usage_countinteger
Quantas vezes já foi usada em pedidos.
valid_fromstring (RFC 3339)
Início da vigência, em UTC.
valid_untilstring (RFC 3339) | null
Fim da vigência, em UTC. null = sem fim.
statusstring
Letra do status: A ativa, D inativa, E expirada.
priorityinteger
Ordem de avaliação. Menor número é avaliado primeiro.
stop_other_rulesboolean
Quando true, as promoções seguintes deixam de ser avaliadas.
stackableboolean
Quando true, pode se combinar com outras promoções acumuláveis.
zonestring
cart (carrinho) ou catalog (preço na vitrine).
bonus_typestring | null
Tipo de bônus único (formato antigo). Prefira bonuses.
bonus_configobject | null
Configuração do bônus único (formato antigo).
bonusesarray
Lista de bônus. Cada item tem bonus_type e config.
free_shipping_method_iduuid | null
Forma de envio que ganha frete grátis, quando o tipo é free_shipping.
labelsobject
Só no detalhe de uma promoção: mapa de id para nome (produto, categoria, seller, grupo) de tudo que as condições citam.
catalog_scopeobject | omitted
Só em promoções de catálogo: alcance real, com store_wide (loja toda), products e categories (quantidades).
created_atstring (RFC 3339)
Criação.
updated_atstring (RFC 3339)
Última alteração.
promotion_id, coupon_id, bonus_value, from_date, expiry_date, users, timestamp, updated_timestampmixed
Apelidos que repetem id, discount, valid_from, valid_until (estes dois em segundos Unix), usage_count e as datas de criação e alteração. coupon_id só vem quando há código. Em integrações novas ignore-os.

Erros: detalhar

StatusQuandoCorpo de exemplo
401Token ausente ou inválido.{"error":"authentication required"}
403O módulo promotions está desligado na loja.{"error":"module_disabled","module":"promotions"}
403O usuário não tem o privilégio exigido (view_promotions para ler, manage_promotions para gravar).{"error":"insufficient privileges","required":"manage_promotions"}
400O id não é um UUID completo (inclui a palavra bulk por engano).{"error":"invalid id","detail":"o id da promoção precisa ser o uuid completo ..."}
404Não existe promoção com esse id.{"error":"promotion not found"}
Achando uma promoção pelo cupom

Para descobrir quem é a dona de um código, use ?search=CODIGO na lista. É também o que a mensagem do 409 coupon_code_in_use sugere.

Lista grande

Lojas migradas podem ter dezenas de milhares de promoções (a loja de testes tem mais de 21 mil). Sempre filtre por status, zone ou search e pagine; para desativar muitas de uma vez use Ações em lote.

Veja também

  • Promoções: visão geral
  • Criar promoção
  • Alterar e excluir
Anterior
Promoções e cupons
Próxima
Criar promoção
Nesta página
  • Listar promoções
  • Exemplo de requisição: listar
  • Resposta: listar
  • Erros: listar
  • Detalhar uma promoção
  • Exemplo de requisição: detalhar
  • Resposta: detalhar
  • Erros: detalhar
  • Veja também