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

# Pagination: Page and Limit Parameters for List Endpoints

> All list endpoints in the Ecommerce API use cursor-free page-based pagination. Learn how to use the page and limit parameters and read the meta object.

Every list endpoint in the Ecommerce API uses page-based pagination. Instead of cursors or offsets, you pass a 1-based `page` number and a `limit` to control how many items are returned per page. Every paginated response wraps the result array in a `data` field and includes a `meta` object that tells you exactly where you are in the full result set and whether more pages exist.

## Query Parameters

Use these query parameters on any list endpoint to control pagination.

<ParamField query="page" type="integer" default="1">
  The page number to retrieve. Pages are 1-based, so the first page is `page=1`. Requesting a page beyond `totalPages` returns an empty `data` array with an accurate `meta` object.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  The number of items to return per page. Accepts values between `1` and `100`. Requests above `100` are rejected with a `400` validation error. When omitted, the API defaults to `20` items per page.
</ParamField>

## Response Meta

Every paginated response includes a `meta` object alongside the `data` array. Use the fields in `meta` to build navigation controls and know when to stop fetching.

```json theme={null}
{
  "success": true,
  "data": [...],
  "meta": {
    "page": 2,
    "limit": 10,
    "total": 47,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": true
  }
}
```

<ResponseField name="meta.total" type="integer">
  The total number of items matching the current query filters across all pages. For example, if you search for products with the query `"shoe"` and 47 results exist, `total` is `47` regardless of the current page.
</ResponseField>

<ResponseField name="meta.totalPages" type="integer">
  The total number of pages available given the current `limit`. Computed as `Math.ceil(total / limit)`. A result set with `total: 0` returns `totalPages: 0`.
</ResponseField>

<ResponseField name="meta.hasNext" type="boolean">
  `true` when there is at least one more page after the current page. Use this field in infinite-scroll or "Load more" UIs to decide whether to fetch the next page.
</ResponseField>

<ResponseField name="meta.hasPrev" type="boolean">
  `true` when the current page is greater than `1` and previous pages exist. Use this to enable "Previous" buttons in paginated UIs.
</ResponseField>

## Example: Fetching Page 2 of Products

The following request fetches the second page of products with 10 items per page. No authentication is required because the product listing endpoint is public.

```bash theme={null}
curl https://api.example.com/api/v1/products?page=2&limit=10
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": [
    {
      "public_id": "prd_01H",
      "name": "Classic Running Shoe",
      "brand": "FleetFoot",
      "created_at": "2024-03-15T10:22:00Z",
      "updated_at": "2024-05-01T08:00:00Z"
    },
    {
      "public_id": "prd_02H",
      "name": "Trail Blazer Boot",
      "brand": "TerraTread",
      "created_at": "2024-03-18T14:11:00Z",
      "updated_at": "2024-04-28T09:45:00Z"
    }
  ],
  "meta": {
    "page": 2,
    "limit": 10,
    "total": 47,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": true
  }
}
```

<Tip>
  To iterate through all pages programmatically, check `meta.hasNext` after each response rather than computing `page < meta.totalPages` yourself. If filters are applied (e.g. a search query), the `total` count reflects only matching results and can change between requests if new data is added concurrently. Relying on `hasNext` keeps your pagination loop correct under those conditions.
</Tip>