Pular para o conteúdo principal
GET
List coupons

📌 Endpoint

GET /stores/{storeId}/coupons Lista os cupons da loja (não expirados). Os cupons são retornados na ordem de position (ascendente).

🔐 Autenticação

  • Rota privada.
  • Requer header Authorization com sua API key e plano ativo.

🧾 Parâmetros de rota


✅ Exemplo de requisição


🔎 Query params


🔄 Paginação por cursor

Para listas grandes (mais de ~100 itens), prefira paginação por cursor no lugar de page:
  1. Faça a primeira chamada sem cursor.
  2. Se hasMore for true, a resposta traz o campo nextCursor.
  3. Envie esse nextCursor no parâmetro cursor da próxima requisição para buscar a página seguinte.
No modo cursor, a paginação é retornada apenas com nextCursor, hasMore e limit:
  • cursor e page não podem ser usados juntos (400 INVALID_PAGINATION).
  • nextCursor: null com hasMore: false indicam o fim da lista (apenas no modo cursor a API responde 200 com array vazio []; no modo offset com page, quando o total é 0, a API retorna 404 COUPONS_NOT_FOUND).

Snippet padrão (cURL)

Use o exemplo cURL da seção Exemplo de requisição acima como snippet oficial.

📦 Resposta de sucesso (200)

A primeira chamada (sem cursor) já retorna nextCursor e hasMore na paginação, permitindo iniciar a paginação por cursor sem chamadas extras.

⚠️ Possíveis erros

  • 400 INVALID_DATA → parâmetros inválidos
  • 400 INVALID_PAGINATION_LIMIT → limit fora do intervalo permitido (1 a 100)
  • 400 INVALID_PAGINATION_PAGE → page inválida
  • 400 INVALID_PAGINATION_CURSOR → cursor inválido ou malformado
  • 400 INVALID_PAGINATION → page e cursor utilizados juntos
  • 401 API_KEY_NOT_PROVIDED → header Authorization não enviado
  • 401 INVALID_API_KEY → API key inválida
  • 401 UNAUTHENTICATED → usuário não autenticado
  • 403 USER_DISABLED → usuário desativado
  • 403 NO_ACTIVE_SUBSCRIPTION → sem plano ativo
  • 404 STORE_NOT_FOUND → loja não encontrada
  • 404 COUPONS_NOT_FOUND → nenhum cupom encontrado (retornado no modo offset quando o total é 0; apenas o modo cursor retorna 200 com [])
  • 429 RATE_LIMIT_EXCEEDED → limite de requisições por minuto excedido
  • 500 INTERNAL_SERVER_ERROR → erro interno
  • 503 SERVICE_UNAVAILABLE → serviço indisponível

Autorizações

Authorization
string
header
padrão:YOUR_API_KEY_HERE
obrigatório

Parâmetros de caminho

storeId
string
obrigatório
Required string length: 1 - 50

Parâmetros de consulta

page
integer
padrão:1
Intervalo obrigatório: x >= 1
limit
integer
padrão:20
Intervalo obrigatório: 1 <= x <= 100
cursor
string

Opaque cursor from previous page (do not combine with page).

Resposta

List coupons.

code
string
obrigatório
Exemplo:

"COUPONS_FETCHED"

coupons
object[]
obrigatório
pagination
object
obrigatório