Next page token pagination method

To view this content in our official product documentation, click here.

Overview

This method is a slight variation on the next page URL approach. Instead of receiving a full URL in the response, it contains a 'token' (usually a random string/hash). The receiving system uses this token to keep track of the position of the last record in the current page of data.

Next page token options

Option	Summary
Token parameter name	Enter the name of the URL parameter which holds the token for requesting the next page.
Limit parameter path	Enter the dot notation path for the data element in your response which contains the maximum number of items that the API should return in a single page of a paginated response. Commonly (though not necessarily), this would be a path to a limit field.
Limit	Enter the number of items to be returned per page. For example: 10.
Path to token in payload	Enter the dot notation path of the next page token within the payload.

Example

Suppose we set the following options:

Option	Value
Token parameter name	page_token
Limit parameter path	limit
Limit	10
Path to token in payload	links.next

...and we send a request to get the first page of data:

{% code lineNumbers="true" %}

GET https://my.shop/api/customers?limit=10

The response will include the first page of data, together with a next page token that should be used to get the next page of results. For example:

{% code lineNumbers="true" %}

{
  "data": [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"},
    {"id": 3, "name": "Charlie"},
    {"id": 4, "name": "Lyn"},
    {"id": 5, "name": "John"},
    {"id": 6, "name": "Gordon"},
    {"id": 7, "name": "Izzy"},
    {"id": 8, "name": "Mike"},
    {"id": 9, "name": "Ralph"},
    {"id": 10, "name": "Rex"}
  ],
  "links": {
    "next": "abcd5780HJKLMN0PqR24"
  }
}

Notice the links.next section at the end of this response, which includes our next page URL. So, our request for the next page of results would be:

{% code lineNumbers="true" %}

GET https://my.shop/api/customers?limit=10&page_token=abcd5780HJKLMN0PqR24

When does pagination stop?

Pagination continues until the token is no longer included in the payload.