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

# Buscar cupons

> Busque cupons por código ou nome, e filtre por estado, tipo ou filial.

<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: `active`, `scheduled`, `expired`, `depleted` ou `inactive`.
</ParamField>

<ParamField body="search" type="object">
  Objeto de busca por texto.

  <Expandable title="Propriedades de busca">
    <ParamField body="value" type="string" required>
      Texto a buscar nos campos `code` e `name`.
    </ParamField>

    <ParamField body="case_sensitive" type="boolean" default="false">
      Define se a busca diferencia maiúsculas de minúsculas.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="filters" type="object[]">
  Lista de filtros a aplicar.

  <Expandable title="Propriedades de cada filtro">
    <ParamField body="field" type="string" required>
      Campo pelo qual filtrar: `status`, `discount_type`, `applies_to_all_branches` ou `branches.id`.
    </ParamField>

    <ParamField body="operator" type="string" default="=">
      Operador de comparação. Valores suportados: `=`, `!=`, `<`, `<=`, `>`, `>=`, `like`, `not like`, `in`, `not in`.
    </ParamField>

    <ParamField body="value" type="string | boolean" required>
      Valor do filtro.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="sort" type="object[]">
  Ordenação dos resultados.

  <Expandable title="Propriedades de cada sort">
    <ParamField body="field" type="string" required>
      Campo pelo qual ordenar: `created_at`, `valid_from`, `valid_until`, `code` ou `status`.
    </ParamField>

    <ParamField body="direction" type="string" default="asc">
      Direção da ordenação: `asc` ou `desc`.
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://gateway.jelou.ai/ecommerce/v2/apps/{app_id}/coupons/search?page=1&limit=20" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "search": {
        "value": "black",
        "case_sensitive": false
      },
      "filters": [
        { "field": "discount_type", "operator": "=", "value": "percentage" },
        { "field": "status", "operator": "=", "value": true }
      ],
      "sort": [
        { "field": "valid_until", "direction": "asc" }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "data": [
      {
        "id": "9e3f2c1a-8b7d-4e6f-a5c4-d3b2a1e0f9c8",
        "code": "BLACKFRIDAY25",
        "name": "Black Friday 25%",
        "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"
      }
    ],
    "meta": {
      "current_page": 1,
      "per_page": 15,
      "total": 1
    }
  }
  ```
</ResponseExample>

<Tip>
  **Campos buscáveis:** `code`, `name`
  **Campos filtráveis:** `status`, `discount_type`, `applies_to_all_branches`, `branches.id`
  **Campos ordenáveis:** `created_at`, `valid_from`, `valid_until`, `code`, `status`
</Tip>