Listar cupons

Liste os cupons da sua conta com paginação e filtros (nome, código, tipo de desconto, status e intervalo de datas). Use esta operação para popular telas de administração, montar relatórios de campanha ou localizar um cupom específico antes de lê-lo, editá-lo ou removê-lo.

GET /v1/coupons

Como funciona

A listagem devolve um objeto paginado: um envelope com metadados de paginação (offset, limit, total, page, hasMore) e um array data com os cupons. Cada item de data é uma projeção leve do cupom — traz os campos de identificação e vigência (id, name, code, type, value, enabled, initDate, endDate, createdAt, updatedAt), mas omite os campos de regras de uso (minCartAmount, usageLimit, allowedItemIds, etc.). Para o cupom completo, faça um Read pelo id.

"Projeção leve" = a lista entrega só o suficiente para você decidir qual cupom abrir; os detalhes vêm no recurso individual.

O servidor aplica os filtros que você enviar como parâmetros de query (combinados com E lógico) e ordena pelo campo de data de criação, na direção que você pedir. A paginação é por offset/limit: você pede uma "janela" de resultados e avança movendo o offset.

Para o padrão completo de janelas, hasMore e como percorrer todas as páginas, veja Paginação.

Quando usar

• Telas de administração / busca: liste e filtre cupons por name, code ou status.
• Relatórios de campanha: combine type, status e o intervalo daterange* para recortar cupons criados em uma janela.
• Localizar antes de agir: encontre o id de um cupom para depois chamar Read, Update ou Delete.

Quando NÃO usar:

• Se você já tem o id, vá direto ao Read — é mais barato que listar e filtrar.
• Se precisa de todos os cupons da conta de uma vez (sem montar paginação), use a variante GET /v1/coupons/listall, que retorna um array direto. Veja List all abaixo.

Requisição

Headers

Autentique sempre pelo header SelectKey — nunca Authorization: Bearer/Basic. Detalhes em Autenticação. Como é uma leitura (GET), não há corpo nem Content-Type.

Parâmetros de query

Todos opcionais; combine-os à vontade.

Exemplo de requisição

curl -G "https://api.selectwin.io/v1/coupons" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  --data-urlencode "status=active" \
  --data-urlencode "type=percentage" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0" \
  --data-urlencode "sort=descending"

Resposta

200 OK — objeto paginado. O array data traz a projeção leve de cada cupom.

{
  "offset": 0,
  "limit": 20,
  "total": 12,
  "page": {
    "offset": {
      "first": 0,
      "prev": null,
      "next": null,
      "last": 0
    },
    "current": 1,
    "total": 1
  },
  "data": [
    {
      "id": "dis_01hqzvabc",
      "name": "Black Friday 25%",
      "code": "BLACKFRIDAY25",
      "type": "percentage",
      "value": 25,
      "enabled": true,
      "initDate": "2026-04-01T00:00:00.000Z",
      "endDate": "2026-04-30T23:59:59.000Z",
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "hasMore": false
}

Campos do envelope

Campos de cada item (data[])

Listar tudo (/listall)

GET /v1/coupons/listall

Variante que retorna todos os cupons da conta como um array direto (sem o envelope de paginação). Útil para exportações e sincronizações em lote, quando você quer o conjunto inteiro sem percorrer páginas.

curl "https://api.selectwin.io/v1/coupons/listall" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

[
  {
    "id": "dis_01hqzvabc",
    "name": "Black Friday 25%",
    "code": "BLACKFRIDAY25",
    "type": "percentage",
    "value": 25,
    "enabled": true,
    "initDate": "2026-04-01T00:00:00.000Z",
    "endDate": "2026-04-30T23:59:59.000Z",
    "updatedAt": "2026-04-12T17:56:33.000Z",
    "createdAt": "2026-04-12T17:56:33.000Z"
  }
]

Erros

O corpo de erro segue o envelope padrão com error.code estável — trate sempre pelo code, não pela message. Veja Tratamento de Erros e o Catálogo de Códigos de Erro.

Boas práticas

• Filtre no servidor, não no cliente. Para grandes volumes, restrinja com status, type, code e daterange* em vez de baixar tudo e filtrar localmente.
• Pagine sempre. Use limit (máx. 50) e avance o offset; pare quando hasMore for false. Veja Paginação.
• Busca por código. Quer um cupom por código de checkout? Use code=SUMMER2026 — costuma retornar um único item.
• Lista é leve. Não confie na lista para regras de uso (usageLimit, minCartAmount, allowedItemIds): esses campos só vêm no Read individual.
• Recortes por data. Combine daterangegte/daterangelte (inclusivos) ou daterangegt/daterangelt (exclusivos) para janelas precisas — sempre em ISO 8601 UTC.
• /listall com parcimônia. Reserve para exportações pontuais; para UI paginada, fique no GET /v1/coupons.

Veja também

• Visão geral de Cupons
• Criar cupom
• Ler cupom
• Atualizar cupom
• Excluir cupom
• Paginação · Convenções · Autenticação