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

# List coupons

> Returns the paginated list of coupons for your store.

<ParamField path="app_id" type="string" required>
  Your store ID in Jelou Shop.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number to return.
</ParamField>

<ParamField query="limit" type="integer" default="15">
  Number of results per page (max. 100).
</ParamField>

<ParamField query="state" type="string">
  Filter by the coupon's derived state. Values: `active`, `scheduled`, `expired`, `depleted`, `inactive`.
</ParamField>

## Coupon states

The `state` field is computed (not stored) from the status, validity window, and usage. Precedence: inactive → scheduled → expired → depleted → active.

| State       | Meaning                                       |
| ----------- | --------------------------------------------- |
| `active`    | Active and applicable.                        |
| `scheduled` | Scheduled: its `valid_from` is in the future. |
| `expired`   | Expired: its `valid_until` has passed.        |
| `depleted`  | Depleted: it reached its `max_uses`.          |
| `inactive`  | Manually deactivated (`status: false`).       |

## Response fields

Each coupon in `data` contains the following fields:

| Field                     | Type            | Description                        |
| ------------------------- | --------------- | ---------------------------------- |
| `id`                      | string          | Coupon UUID                        |
| `code`                    | string          | Code the customer enters           |
| `name`                    | string          | Internal name                      |
| `description`             | string \| null  | Description                        |
| `discount_type`           | string          | `percentage` or `value`            |
| `discount_value`          | string          | Discount value                     |
| `status`                  | boolean         | Whether it is active               |
| `valid_from`              | string \| null  | Validity start                     |
| `valid_until`             | string \| null  | Validity end                       |
| `max_uses`                | integer \| null | Total usage limit                  |
| `once_per_client`         | boolean         | One use per customer               |
| `applies_to_all_branches` | boolean         | Whether it applies to all branches |
| `uses_count`              | integer         | Number of times it has been used   |
| `state`                   | string          | Derived state (see table)          |
| `created_at`              | string          | Creation date                      |
| `updated_at`              | string          | Last update date                   |

<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% off the entire store",
        "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>
  To include the assigned branches in the response, request the `branches` relation (for example `?include=branches`). To sort or filter by more fields, use [Search coupons](/en/guides/integraciones/e-commerce/api-cupones/buscar).
</Note>

<Tip>
  **Coupon uses:** get the detail of each redemption (customer, branch, cart) with `GET https://gateway.jelou.ai/ecommerce/v2/coupons/{coupon_id}/uses`. It supports the `branch_id` and `client_id` filters.
</Tip>