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.

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.

Scroll is a separate mechanism from _page pagination — they cannot be combined. For shallow queries (_page ≤ 500), existing pagination continues to work as before.

---

🛠️ How It Works

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

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.

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.

{
  "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.

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

For very large datasets and offline processing, the platform's Data Export functionality is also available as an alternative.