# Scroll Mechanism for Pages

## Scroll Mechanism for Pages

### 🧩 How to Use the Scroll Mechanism in Open Loyalty API

To efficiently retrieve large datasets via the API, we recommend using the scrolling mechanism instead of traditional pagination with `_page`. This method is optimized for performance when fetching a high volume of records and has **no page-depth limit**.

{% hint style="warning" %}
**Action required if you use deep pagination**

From **15 September 2026**, the `_page` parameter is limited to a maximum value of **500** on key list endpoints (Custom events, Members, Member history, Audit log, Transactions, Unit transfers, Issue rewards, Group of values). Requests with `_page` higher than 500 will return an error.

If your integration currently uses `_page` values above 500, migrate to the scroll mechanism described on this page before that date.
{% endhint %}

{% hint style="info" %}
Scroll is a **separate mechanism** from `_page` pagination — they cannot be combined. For shallow queries (`_page` ≤ 500), existing pagination continues to work as before.
{% endhint %}

***

### 🛠️ How It Works

The scrolling process involves an initial request followed by sequential calls using a token to retrieve subsequent pages of data.

{% hint style="warning" %}
**IMPORTANT**

* Do not combine `_scroll` with `_page` or `_orderBy` parameters in your requests. These parameters will be ignored when scrolling is active.
* Scroll always returns results sorted by `createdAt DESC` (newest first). This sorting order cannot be customized.
* Scroll tokens are encoded and should be used exactly as provided. Do not modify them manually.
  {% endhint %}

#### 1. Initial Request

Start the scrolling process by sending a request with the `_scroll` parameter, e.g.:

```
GET /api/{storeCode}/member?_scroll
```

The parameter can be added alongside other queries, e.g.:

```
GET /api/{storeCode}/member?_scroll&registeredAt[gte]=2025-01-01T00:00:00Z
```

#### 2. Response

The API will return the first set of results along with a `scroll.next` token.

```json
{
  "items": [...],
  "scroll": {
    "next": "scrollTokenHere"
  }
}
```

#### 3. Next Page

Use the `scroll.next` token from the previous response to retrieve the next page of results.

```
GET /api/{storeCode}/member?_scroll=scrollTokenHere
```

#### 4. Repeat

Continue making requests using the new `scroll.next` token returned in each response to cycle through all the data.

#### 5. End of Results

Once you have retrieved all the available data, the API will return an empty `items` array and an empty `scroll` object, indicating the end of the dataset.

```json
{
  "items": [],
  "scroll": {}
}
```

***

### ✅ Supported Endpoints

The `_scroll` mechanism is supported on the following endpoints:

* `/api/{storeCode}/customEvent`
* `/api/{storeCode}/member`
* `/api/{storeCode}/points`
* `/api/{storeCode}/transaction`
* `/api/{storeCode}/groupOfValues`
* `/api/{storeCode}/redemption`

{% hint style="info" %}
For very large datasets and offline processing, the platform's [Data Export](/technical-guide/data-exports/overview.md) functionality is also available as an alternative.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.openloyalty.io/technical-guide/api-fundamentals/scroll-mechanism-for-pages.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.