Pular para o conteúdo principal
GET
/
ecommerce
/
v2
/
apps
/
{app_id}
/
coupons
curl "https://gateway.jelou.ai/ecommerce/v2/apps/{app_id}/coupons?page=1&limit=20&state=active" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": [
    {
      "id": "9e3f2c1a-8b7d-4e6f-a5c4-d3b2a1e0f9c8",
      "code": "BLACKFRIDAY25",
      "name": "Black Friday 25%",
      "description": "25% de desconto em toda a loja",
      "discount_type": "percentage",
      "discount_value": "25.000000",
      "status": true,
      "valid_from": "2026-11-25T00:00:00.000000Z",
      "valid_until": "2026-11-30T23:59:59.000000Z",
      "max_uses": 100,
      "once_per_client": true,
      "applies_to_all_branches": true,
      "uses_count": 0,
      "state": "scheduled",
      "created_at": "2026-07-02T15:30:00.000000Z",
      "updated_at": "2026-07-02T15:30:00.000000Z"
    }
  ],
  "links": {
    "first": "https://gateway.jelou.ai/ecommerce/v2/apps/{app_id}/coupons?page=1",
    "last": "https://gateway.jelou.ai/ecommerce/v2/apps/{app_id}/coupons?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "per_page": 15,
    "to": 1,
    "total": 1
  }
}
​
app_id
string
obrigatório
O ID da sua loja no Jelou Shop.
​
page
integer
padrão:"1"
Número da página a retornar.
​
limit
integer
padrão:"15"
Quantidade de resultados por página (máx. 100).
​
state
string
Filtra pelo estado derivado do cupom. Valores: active, scheduled, expired, depleted, inactive.

​
Estados do cupom

O campo state é calculado (não é armazenado) a partir do status, da vigência e dos usos. Precedência: inativo → agendado → expirado → esgotado → ativo.
EstadoSignificado
activeAtivo e aplicável.
scheduledAgendado: seu valid_from é futuro.
expiredExpirado: seu valid_until já passou.
depletedEsgotado: atingiu seu max_uses.
inactiveDesativado manualmente (status: false).

​
Campos da resposta

Cada cupom em data contém os seguintes campos:
CampoTipoDescrição
idstringUUID do cupom
codestringCódigo que o cliente insere
namestringNome interno
descriptionstring | nullDescrição
discount_typestringpercentage ou value
discount_valuestringValor do desconto
statusbooleanSe está ativo
valid_fromstring | nullInício da vigência
valid_untilstring | nullFim da vigência
max_usesinteger | nullLimite total de usos
once_per_clientbooleanUm uso por cliente
applies_to_all_branchesbooleanSe aplica a todas as filiais
uses_countintegerQuantas vezes foi usado
statestringEstado derivado (ver tabela)
created_atstringData de criação
updated_atstringData da última atualização
curl "https://gateway.jelou.ai/ecommerce/v2/apps/{app_id}/coupons?page=1&limit=20&state=active" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": [
    {
      "id": "9e3f2c1a-8b7d-4e6f-a5c4-d3b2a1e0f9c8",
      "code": "BLACKFRIDAY25",
      "name": "Black Friday 25%",
      "description": "25% de desconto em toda a loja",
      "discount_type": "percentage",
      "discount_value": "25.000000",
      "status": true,
      "valid_from": "2026-11-25T00:00:00.000000Z",
      "valid_until": "2026-11-30T23:59:59.000000Z",
      "max_uses": 100,
      "once_per_client": true,
      "applies_to_all_branches": true,
      "uses_count": 0,
      "state": "scheduled",
      "created_at": "2026-07-02T15:30:00.000000Z",
      "updated_at": "2026-07-02T15:30:00.000000Z"
    }
  ],
  "links": {
    "first": "https://gateway.jelou.ai/ecommerce/v2/apps/{app_id}/coupons?page=1",
    "last": "https://gateway.jelou.ai/ecommerce/v2/apps/{app_id}/coupons?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "per_page": 15,
    "to": 1,
    "total": 1
  }
}
Para incluir as filiais atribuídas na resposta, solicite a relação branches (por exemplo ?include=branches). Para ordenar ou filtrar por mais campos, use Buscar cupons.
Usos de um cupom: consulte o detalhe de cada resgate (cliente, filial, carrinho) com GET https://gateway.jelou.ai/ecommerce/v2/coupons/{coupon_id}/uses. Suporta os filtros branch_id e client_id.