> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar cupons

> Retorna a lista paginada de cupons da sua loja.

<ParamField path="app_id" type="string" required>
  O ID da sua loja no Jelou Shop.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Número da página a retornar.
</ParamField>

<ParamField query="limit" type="integer" default="15">
  Quantidade de resultados por página (máx. 100).
</ParamField>

<ParamField query="state" type="string">
  Filtra pelo estado derivado do cupom. Valores: `active`, `scheduled`, `expired`, `depleted`, `inactive`.
</ParamField>

## 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.

| Estado      | Significado                               |
| ----------- | ----------------------------------------- |
| `active`    | Ativo e aplicável.                        |
| `scheduled` | Agendado: seu `valid_from` é futuro.      |
| `expired`   | Expirado: seu `valid_until` já passou.    |
| `depleted`  | Esgotado: atingiu seu `max_uses`.         |
| `inactive`  | Desativado manualmente (`status: false`). |

## Campos da resposta

Cada cupom em `data` contém os seguintes campos:

| Campo                     | Tipo            | Descrição                    |
| ------------------------- | --------------- | ---------------------------- |
| `id`                      | string          | UUID do cupom                |
| `code`                    | string          | Código que o cliente insere  |
| `name`                    | string          | Nome interno                 |
| `description`             | string \| null  | Descrição                    |
| `discount_type`           | string          | `percentage` ou `value`      |
| `discount_value`          | string          | Valor do desconto            |
| `status`                  | boolean         | Se está ativo                |
| `valid_from`              | string \| null  | Início da vigência           |
| `valid_until`             | string \| null  | Fim da vigência              |
| `max_uses`                | integer \| null | Limite total de usos         |
| `once_per_client`         | boolean         | Um uso por cliente           |
| `applies_to_all_branches` | boolean         | Se aplica a todas as filiais |
| `uses_count`              | integer         | Quantas vezes foi usado      |
| `state`                   | string          | Estado derivado (ver tabela) |
| `created_at`              | string          | Data de criação              |
| `updated_at`              | string          | Data da última atualização   |

<RequestExample>
  ```bash cURL theme={null}
  curl "https://gateway.jelou.ai/ecommerce/v2/apps/{app_id}/coupons?page=1&limit=20&state=active" \
    -H "x-api-key: YOUR_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "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
    }
  }
  ```
</ResponseExample>

<Note>
  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](/pt/guias/integracoes/e-commerce/api-cupones/buscar).
</Note>

<Tip>
  **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`.
</Tip>