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.

---

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