---
title: "Listar promoções"
method: GET
path: "/api/promotions"
tags: ["Admin API · Promoções"]
---

# Listar promoções

`GET /api/promotions`

## Request

- Base URL: `https://sualoja.commerce-wake.tech`
- URL: `https://sualoja.commerce-wake.tech/api/promotions`
- Auth: HTTP bearer

Retorna as promoções da loja (exceto as excluídas), com filtros e paginação.
            
Permissão: **Cadastro de promoções — visualização**.
            
O parâmetro `status` aceita, sem diferenciar maiúsculas:
- **Ativa**: promoções atualmente em vigor
- **Inativa**: promoções desativadas
- **Expirada**: promoções com a vigência encerrada
- **Programada**: promoções ativas com início futuro
            
Valores fora das faixas e listas aceitas retornam `400` (`VALIDATION_FAILED`), com o parâmetro em `details[].field`.

## Query parameters

- `InitialDate` string, date-time, nullable: Início do período a filtrar. Só tem efeito junto com `finalDate`: retorna as promoções cuja vigência se sobrepõe ao período.
- `FinalDate` string, date-time, nullable: Fim do período a filtrar. Só tem efeito junto com `initialDate`.
- `PromotionsDate` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13
- `Page` integer, nullable: Página, começando em 1. Padrão: 1.
- `Limit` integer, nullable: Itens por página, de 1 a 100. Padrão: 10.
- `OrderField` string, nullable: Campo de ordenação: `name`, `initialDate`, `finalDate` ou `order` (prioridade), exatamente com essa grafia. Padrão: `order`.
- `OrderBy` string, nullable: Direção da ordenação: `asc` ou `desc`. Padrão: `desc`.
- `Search` string, nullable: Trecho do nome, ID exato ou código de cupom. %, _ e [ são buscados como texto.
- `Active` boolean, nullable: Filtra pelo indicador de ativação.
- `CanAccumulate` boolean, nullable: Filtra pelo indicador de acúmulo.
- `HasMultipleCoupons` boolean, nullable: Somente promoções com múltiplos cupons.
- `Conditions` integer[], nullable: Promoções que usam estes tipos de condição (`promotionConditionId` de GET /api/promotions/conditions). Repita a chave para vários valores.
- `Actions` integer[], nullable: Promoções que usam estes tipos de ação (`promotionActionId` de GET /api/promotions/actions). Repita a chave para vários valores.
- `HasCoupons` boolean, nullable: Somente promoções com (`true`) ou sem (`false`) cupom.
- `Status` string, nullable: Filtro por status da promoção. Valores aceitos: "Ativa", "Inativa", "Expirada", "Programada"

## Headers

- `x-api-version` '2.0', required

## Response `200`

Página de promoções. `data` traz os itens; `total` é o total que atende aos filtros.

- PromotionsDataDTO
  - `promotions` PromotionDTO[], nullable: Legado: mesmo conteúdo de `data`. Prefira `data`.
    - `promotionId` integer: ID da promoção.
    - `name` string, nullable: Nome da promoção.
    - `description` string, nullable: Sempre `null` na listagem. Use Obter promoção.
    - `initialDate` string, date-time: Início da vigência.
    - `finalDate` string, date-time: Fim da vigência.
    - `active` boolean: Indicador de ativação.
    - `coupons` string[], nullable: Códigos de cupom.
    - `order` integer, nullable: Prioridade (menor = avaliada antes). Pode ser `null`.
    - `totalCouponsPerCustomer` integer: Limite de usos por cliente (0 = ilimitado).
    - `totalCouponsLimit` integer: Limite total de usos (0 = ilimitado).
    - `totalCouponsUsed` integer: Usos já realizados (pedidos cancelados não contam).
    - `canAccumulate` boolean: Se acumula com outras promoções.
    - `accumulationScope` 0 | 1 | 2: Escopo de acúmulo de uma promoção que permite acumular. O lojista escolhe UM escopo por promoção — nunca mistura inclusão com exclusão.
    - `accumulationLinkCount` integer: Quantidade de promoções vinculadas na lista de acúmulo desta promoção.
    - `status` string, nullable: Status calculado na consulta: Ativa, Inativa, Expirada ou Programada.
    - `hasCoupon` boolean: Se a promoção depende de cupom.
    - `hasMultipleCoupons` boolean: Se a promoção tem mais de um código de cupom.
  - `data` PromotionDTO[], nullable: Promoções da página.
    - `promotionId` integer: ID da promoção.
    - `name` string, nullable: Nome da promoção.
    - `description` string, nullable: Sempre `null` na listagem. Use Obter promoção.
    - `initialDate` string, date-time: Início da vigência.
    - `finalDate` string, date-time: Fim da vigência.
    - `active` boolean: Indicador de ativação.
    - `coupons` string[], nullable: Códigos de cupom.
    - `order` integer, nullable: Prioridade (menor = avaliada antes). Pode ser `null`.
    - `totalCouponsPerCustomer` integer: Limite de usos por cliente (0 = ilimitado).
    - `totalCouponsLimit` integer: Limite total de usos (0 = ilimitado).
    - `totalCouponsUsed` integer: Usos já realizados (pedidos cancelados não contam).
    - `canAccumulate` boolean: Se acumula com outras promoções.
    - `accumulationScope` 0 | 1 | 2: Escopo de acúmulo de uma promoção que permite acumular. O lojista escolhe UM escopo por promoção — nunca mistura inclusão com exclusão.
    - `accumulationLinkCount` integer: Quantidade de promoções vinculadas na lista de acúmulo desta promoção.
    - `status` string, nullable: Status calculado na consulta: Ativa, Inativa, Expirada ou Programada.
    - `hasCoupon` boolean: Se a promoção depende de cupom.
    - `hasMultipleCoupons` boolean: Se a promoção tem mais de um código de cupom.
  - `total` integer: Total de promoções que atendem aos filtros (para paginação).
  - `page` integer: Página usada pela listagem (o padrão, quando não informada).
  - `limit` integer: Tamanho de página usado pela listagem (o padrão, quando não informado).

## Other responses

- `400`: Requisição inválida, incluindo a falta do header x-api-version. O motivo vem em details.
- `401`: Token ausente, inválido ou expirado (SESSION_INVALID), ou sem a permissão exigida (UNAUTHORIZED).
- `500`: Erro inesperado. Tente de novo; se persistir, contate o suporte com o traceId.

---

[API](https://skmtc.dev/fbits/apis/admin-api.md) - [All operations](https://skmtc.dev/fbits/apis/admin-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fbits/apis/admin-api/revisions/a37bfd1b0bf3?raw)