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

**app\_id** `string` *required*

ID de tu tienda en Jelou Shop.

**page** `integer` (default: 1)

Número de página a retornar.

**limit** `integer` (default: 15)

Cantidad de resultados por página (máx. 100).

**state** `string`

Filtra por el estado derivado del cupón. Valores: `active`, `scheduled`, `expired`, `depleted`, `inactive`.

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

```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"
```

```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
  }
}
```

> [!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](https://docs.jelou.ai/api/shop/cupones/buscar.md).

> [!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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.