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

> Retorna la lista paginada de cupones de tu tienda.

<ParamField path="app_id" type="string" required>
  ID de tu tienda en Jelou Shop.
</ParamField>

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

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

<ParamField query="state" type="string">
  Filtra por el estado derivado del cupón. Valores: `active`, `scheduled`, `expired`, `depleted`, `inactive`.
</ParamField>

## Estados del cupón

El campo `state` es calculado (no se almacena) a partir del estado, la vigencia y los usos. Precedencia: inactivo → programado → caducado → agotado → activo.

| Estado      | Significado                                |
| ----------- | ------------------------------------------ |
| `active`    | Activo y aplicable.                        |
| `scheduled` | Programado: su `valid_from` es futuro.     |
| `expired`   | Caducado: su `valid_until` ya pasó.        |
| `depleted`  | Agotado: alcanzó su `max_uses`.            |
| `inactive`  | Desactivado manualmente (`status: false`). |

## Campos de la respuesta

Cada cupón en `data` contiene los siguientes campos:

| Campo                     | Tipo            | Descripción                       |
| ------------------------- | --------------- | --------------------------------- |
| `id`                      | string          | UUID del cupón                    |
| `code`                    | string          | Código que ingresa el cliente     |
| `name`                    | string          | Nombre interno                    |
| `description`             | string \| null  | Descripción                       |
| `discount_type`           | string          | `percentage` o `value`            |
| `discount_value`          | string          | Valor del descuento               |
| `status`                  | boolean         | Si está activo                    |
| `valid_from`              | string \| null  | Inicio de vigencia                |
| `valid_until`             | string \| null  | Fin de vigencia                   |
| `max_uses`                | integer \| null | Límite total de usos              |
| `once_per_client`         | boolean         | Un uso por cliente                |
| `applies_to_all_branches` | boolean         | Si aplica a todas las sucursales  |
| `uses_count`              | integer         | Cantidad de veces que se ha usado |
| `state`                   | string          | Estado derivado (ver tabla)       |
| `created_at`              | string          | Fecha de creación                 |
| `updated_at`              | string          | Fecha de última actualización     |

<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: TU_CLAVE_API"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "data": [
      {
        "id": "9e3f2c1a-8b7d-4e6f-a5c4-d3b2a1e0f9c8",
        "code": "BLACKFRIDAY25",
        "name": "Black Friday 25%",
        "description": "25% de descuento en toda la tienda",
        "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 las sucursales asignadas en la respuesta, pide la relación `branches` (por ejemplo `?include=branches`). Para ordenar o filtrar por más campos, usa [Buscar cupones](/guides/integraciones/e-commerce/api-cupones/buscar).
</Note>

<Tip>
  **Usos de un cupón:** consulta el detalle de cada canje (cliente, sucursal, carrito) con `GET https://gateway.jelou.ai/ecommerce/v2/coupons/{coupon_id}/uses`. Admite los filtros `branch_id` y `client_id`.
</Tip>