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

# Pagination, Sorting & Filtering

> How to paginate, sort, and filter results from list endpoints.

## Pagination

All list endpoints use page-number (offset) pagination, controlled by a page number and a page size parameter. There are no cursors: request a specific page directly with `page[number]`.

| Parameter      | Default | Max   | Description      |
| -------------- | ------- | ----- | ---------------- |
| `page[number]` | `1`     | —     | Page number      |
| `page[size]`   | `20`    | `100` | Results per page |

**Pagination metadata** is included in every list response under the `meta` key. Use `total_pages` to know when to stop, and increment `page[number]` to walk through the results.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.mageloyalty.com/v1/customers?page[number]=2&page[size]=50" \
    -H "Authorization: <api-key>"
  ```

  ```javascript Node theme={null}
  const response = await fetch(
    "https://api.mageloyalty.com/v1/customers?page[number]=2&page[size]=50",
    {
      headers: {
        Authorization: "<api-key>",
      },
    }
  );

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.mageloyalty.com/v1/customers",
      headers={"Authorization": "<api-key>"},
      params={"page[number]": 2, "page[size]": 50},
  )

  data = response.json()
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init(
      "https://api.mageloyalty.com/v1/customers?page[number]=2&page[size]=50"
  );
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          "Authorization: <api-key>",
      ],
  ]);
  $data = json_decode(curl_exec($ch), true);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": [
      {
        "type": "customer",
        "id": "6789012345",
        "attributes": {
          "email": "jane@example.com",
          "current_points": 450
        }
      }
    ],
    "meta": {
      "total": 245,
      "page": 2,
      "per_page": 50,
      "total_pages": 5
    }
  }
  ```
</ResponseExample>

## Sorting

Most list endpoints accept a `sort` parameter. Prefix the field name with `-` for descending order.

```bash theme={null}
# Sort by most recent first (descending)
?sort=-created_at

# Sort by name A-Z (ascending)
?sort=name
```

Each endpoint documents its own set of sortable fields. The default sort for all list endpoints is `-created_at` (newest first).

## Filtering

There is no global filter engine. Filtering is endpoint-specific: each list endpoint defines its own `filter[field]` parameters, and only the filters documented on that endpoint are accepted. The examples below are real for the endpoints noted.

```bash theme={null}
# Rewards: filter by active status
?filter[is_active]=true

# Earning history: filter by status
?filter[status]=approved
```

See each endpoint's reference page for the filters it supports.